MUST use HTTP methods correctly [43]
The HTTP verbs which can be used are GET, POST, PUT, PATCH, DELETE, OPTIONS and HEAD. API calls made from the browser often first send an OPTIONS call to the API. The API responds with the possible communication options like the supported HTTP verbs, headers etc. Therefore we make our APIs support OPTIONS calls.
All methods may response with codes 30x, 4xx or 5xx (409 and 415 only with request payload). See also [49].
| HTTP verb | CRUD | Description | Request body? | Query parameters | Success responses |
|---|---|---|---|---|---|
| GET | Read | Should only retrieve data from the resource. | No | Optional | 200 |
| POST | Create | Submit an entity, issue command or invoke complex search. | Yes | No | On create 201 else 200 |
| PUT | Modify | Updates the whole resource. | Yes | See remark | 200 or 204 |
| PATCH | Modify | Updates part of the resource (only modified fields; use PUT for whole object). | Yes | See remark | 200 or 204 |
| DELETE | Delete | Deletes the specified resource. | Optional | No | 204 or 200 |
| OPTIONS | - | Is used to request the possible communication options. | Optional | No | 200 |
| HEAD | - | Identical to a GET request, but does not return a response body | No | No | 200 |
Remark: Query parameters only to uniquely identify resource (if no UUID is present)
MUST use Accept header when applicable [44]
The client must always send an Accept header. This tells the API which Content-Type the client prefers to receive.
MUST use Content-Type header when applicable [45]
The client must send a Content-Type header when the request includes a body. The server should always send a Content-Type header in the response. For REST APIs the standard media type name should be used, for JSON this is “application/json”.
MUST support CORS headers if API can be called from browser [46]
Cross-origin resource sharing (CORS) is a mechanism that allows restricted resources on a web page to be requested from another domain outside the domain from which the first resource was served
APIs that can be called directly from the browser need to support CORS by returning CORS headers.
SHOULD NOT use “X-” prefix on custom headers [47]
Originally it was recommended to prefix custom headers with X-, like X-Custom-Header. This convention was deprecated however in 2012, because of the inconveniences it caused when non-standard fields became standard (https://tools.ietf.org/html/rfc6648 ). We therefore stick to the new recommendation to use meaningful names without the ‘X- ‘prefix.
Example(s):
Powered-By, Apim-Subscription-Key
SHOULD use X-Request-ID [48]
The ‘X-‘ prefix is contradictory with the custom header convention but since X-Request-ID is so widely used it makes sense to use that.
The request to the API should contain the X-Request-ID header which contains a unique ID for this request. It can be used to combine individual traces from the API platform and the backend based on the request Id. It will be set by the API gateway, if not provided by the client.