API Latest

Explore the terminology, conventions, and design patterns behind the two available API types: REST and RPC. Consistent design makes them easy to understand, extend, maintain, and integrate.

PAGE CONTENT

• Terminology
  • Resource (REST)
• REST API Design
  • Operations
• RPC API Design

RELATED PAGES

API Gateway Blueprint Service Blueprint

Terminology

Both APIs share a common vocabulary — REST terms drawn from the OpenAPI 3.1.0 specification and RPC terms from the Cloudflare Workers RPC documentation.

Where the standard vocabulary falls short, this section introduces the additional terms needed to describe the API accurately and completely.

Resource (REST)

A resource carries the same meaning as in the OpenAPI specification and maps to an entity, either a table in the database or a business abstraction over one or more such tables.

REST API Design

The REST API follows resource-oriented design. Each resource maps to a predictable URL and supports a standard set of operations, keeping the interface uniform across the entire surface.

Operations

Operations are the means by which clients act on resources. The sections below describe each one and demonstrate its behavior using the Player resource as an example.

Create

Sending a POST request to the resource path creates a new resource on the server. On success, the server returns 201 Created with the newly created resource in the response body, along with a Location header pointing to the new resource's URL.

Example using the Player entity:

POST /players HTTP/1.1
Content-Type: application/json

{
  "name": "Mia",
  "surname": "Hamm",
  "position": "LW"
}

HTTP/1.1 201 Created
Content-Type: application/json
Location: /players/73fbfd23-990f-4170-bd27-69ed1635c26c

{
  "id": "73fbfd23-990f-4170-bd27-69ed1635c26c",
  "name": "Mia",
  "surname": "Hamm",
  "position": "LW"
}

Read

Sending a GET request to the resource path retrieves a list of all resources. To retrieve a single resource, send a GET request to the path with the resource's ID appended. Both operations return 200 OK with the requested resource in the response body.

Example using the Player entity — listing all players and retrieving a single player by ID:

GET /players HTTP/1.1

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "id": "802e6143-dca1-4235-a1bd-e1a2c6567c86",
    "name": "Ona",
    "surname": "Batlle",
    "position": "ST"
  },
  {
    "id": "e846bc3a-33e5-480f-8217-aaa1cf265bc2",
    "name": "Alex",
    "surname": "Morgan",
    "position": "ST"
  },
  {
    "id": "73fbfd23-990f-4170-bd27-69ed1635c26c",
    "name": "Mia",
    "surname": "Hamm",
    "position": "LW"
  }
]

Example using the Player entity — retrieving a single player by ID:

GET /players/73fbfd23-990f-4170-bd27-69ed1635c26c HTTP/1.1

HTTP/1.1 200 OK
Content-Type: application/json

{
 "id": "73fbfd23-990f-4170-bd27-69ed1635c26c",
 "name": "Mia",
 "surname": "Hamm",
 "position": "LW"
}

Update

Sending a PUT request to the resource path with the resource's ID appended replaces the resource entirely with the provided data. Sending a PATCH request to the same path applies a partial update, changing only the fields included in the request body. Both operations return 200 OK with the updated resource in the response body.

Example using the Player entity — replacing a player:

PUT /players/73fbfd23-990f-4170-bd27-69ed1635c26c HTTP/1.1
Content-Type: application/json

{
  "name": "Alexia",
  "surname": "Putellas",
  "position": "CAM"
}

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": "73fbfd23-990f-4170-bd27-69ed1635c26c",
  "name": "Alexia",
  "surname": "Putellas",
  "position": "CAM"
}

Example using the Player entity — partially updating a player:

PATCH /players/802e6143-dca1-4235-a1bd-e1a2c6567c86 HTTP/1.1
Content-Type: application/json

{
 "position": "RB"
}

HTTP/1.1 200 OK
Content-Type: application/json

{
 "id": "802e6143-dca1-4235-a1bd-e1a2c6567c86",
 "name": "Ona",
 "surname": "Batlle",
 "position": "RB"
}

Delete

Sending a DELETE request to the resource's path removes the resource from the server. On success, the server returns 204 No Content with no response body.

Example using the Player entity:

DELETE /players/e846bc3a-33e5-480f-8217-aaa1cf265bc2 HTTP/1.1

HTTP/1.1 204 No Content

RPC API Design

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Duis nunc ex, euismod ultricies vestibulum elementum, facilisis mollis lorem. Suspendisse luctus sem eget convallis hendrerit. Duis porttitor auctor dolor at ornare.