meticulousengineer

REST over HTTP Cheatsheet for Web APIs

Endpoints conventions

GET /orders returns all orders. The response body must contain the data as an array of orders.
GET /orders/{id} returns the order with identifier {id}. The response body must contain the order data.
POST /orders creates an order using the data provided in the request body. The response body must contain the newly created order data, including a newly generated unique resource identifier.
PUT /orders/{id} updates the whole order resource with identifier {id} using the data provided in the request body. The response body must contain the modified order data. The endpoint must never update the unique identifier of the entity. Favor PATCH instead of PUT.
PATCH /orders/{id}/status partially updates the resource with identifier {id} using the data provided in the request body. The response body must contain the whole modified order.
DELETE /orders/{id} deletes the order with identifier {id}.

Response HTTP status codes

  • 200 OK represents a successful operation
  • 201 CREATED indicates that a resource was successfully created. It is usually used together with POST.
  • 202 ACCEPTED says that the operation was acknowledged by the server and that the operation will complete sometime in the future. Should be used whenever the underlying operation is expensive (eg. takes a long time).
  • 204 NO CONTENT indicates a successful operation with no response body. It is used usually together with the verbs that mutate the data on the server.
  • 400 BAD REQUEST if the request data provided by the client is invalid. It could refer to path variables, query parameters, headers or the body.
  • 401 UNAUTHORIZED if the Authorization header contains invalid data (wrong format, expired, etc.).
  • 403 FORBIDDEN if the Authorization header doesn’t contain all the required privileges for the endpoint execution (ex. a user lacks a permission)
  • 404 NOT FOUND when the URL cannot identify a resource considering all path variables
  • 409 CONFLICT when the request is correct but the processing fails because there’s a conflict between the provided request data and the server’s data
  • 422 UNPROCESSABLE CONTENT indicates that the server understood the request data and considered it as correct, but, based on the provided date, the server successfully process the request. This status code is frequently used to indicate business related errors.
  • 500 INTERNAL SERVER ERROR in case an unexpected error occurs.

Idempotency

The verbs GET, PUT, PATCH, DELETE are idempotent, meaning that the state of the server will remain unchanged after the first request is executed regardless of how many identical requests the server processes.

Response representation

Each response should contain at least one of:

  • data is the data returned from the API
    • should be an array in case the API returns collection of resource representations; if the API returns an empty collection then an empty array should be returned
    • should be the resource representation in case the endpoint returns a single resource; if the resource is not available/found then null should be returned together with the 200 status code OR 404 status code with an empty response body
  • errors indicates that errors occurred during the request processing
  • meta may contain any other non standard data and must be an object

Responses should not contain both data and errors.

Example of a successful response:

[
  "data": {
    "id": "...",
    "name": "John Doe"
  }
]

Each error should contain at least one of the following:

  • id a unique identifier of the error stored in a database or in the logs
  • status required, the HTTP status code, as string, the best describes the problem
  • code application specific error code, as string
  • title a human readable summary of the error (except localization cases)
  • detail a human readable description of the error
  • source indicates where the error happened and should contain one of the following:
  • pointer indicates the place from the request body where the error occurred, ex. /data/name where /data refers to the primary resource and /name represents the name field
  • parameter indicates the query parameter at which the problem occurred
  • header indicates the header at which the problem occurred
  • meta can contain other data related to the error

In case the endpoint needs to return all errors related to the request, the response HTTP status code should be either 400 or 500 depending on the type of errors that occurred.

Example:

[
  "errors": {
    "id": "634ef39d-f253-4598-b59a-bd9089a239e7",
    "status": "422",
    "code": "24205",
    "title": "Failed to re-send the order processed notification",
    "detail": "We were not able to re-send the notification for the processed order",
  }
]

Sorting

GET /orders?sort=created_at,created_by sorts the result in ascending order by created_at and then by created_by
GET /orders?sort=-created_at,created_by sorts the result in descending order by created_at and then in ascending order by created_by

Pagination

GET /orders?page[offset]=5&page[limit]=10 skips the first 5 records and returns the next 5 records

GET /orders?page=2&page_size=50 skips first 50 records and will return the next 50 records.

GET /orders?cursor=b0870299-7de8-4835-9668-67fe434810b4 cursor-based pagination uses a cursor (e.g., an encoded string) to indicate the position of the last item fetched in the previous request. The API then returns the next set of results starting after that cursor. It’s often considered more efficient than offset-based pagination for large datasets since it avoids the “skip” problem

Filtering data

GET /orders?filter[amountRangeMin]=100&filter[amountRangeMax]=3000&filter[created_by]=e058eb69-2e33-4179-ba34-ddd5f5ab9d9a should return the orders created by the user with ID e058eb69-2e33-4179-ba34-ddd5f5ab9d9a which total amount is in range [100, 3000].

Posted

Tags:

, ,