API Design
Deliveroo
API Design
API countsHow many endpoints/resources in an API? |
Global designGeneral considerations on API design
|
API Lifecycle
Updates and VersioningHow to handle API updates and versioning
|
Collection Resources
PaginationHow to retrieve a range of resources in a collection
|
Retrieve a collectionHow to get a collection or resources |
CollectionWhat is a collection (set) of resources |
Data
InternationalizationProviding internationalized data representation (e.g. adapted to the user’s country) |
Error handling
ErrorsHow to handle errors |
Error formatHow to provide information about errors |
HTTP Methods
DELETEThe DELETE method deletes the specified resource. |
GETThe GET method requests a representation of the specified resource. Requests using GET should only retrieve data and should have no other effect. |
HEADThe HEAD method asks for a response identical to that of a GET request, but without the response body. This is useful for retrieving meta-information written in response headers, without having to transport the entire content. |
PATCHThe PATCH method applies partial modifications to a resource.
|
POSTThe POST method requests that the server accept the entity enclosed in the request as a new subordinate of the web resource identified by the URI. The data POSTed might be, for example, an annotation for existing resources; a message for a bulletin board, newsgroup, mailing list, or comment thread; a block of data that is the result of submitting a web form to a data-handling process; or an item to add to a database.
|
HTTP methodsGeneral information about HTTP methods usage |
HTTP Protocol
CachingHow to use and provide relevant caching informations |
Content negociation and media typesHow to describe your API data format and/or propose different formats (like json, yaml, xml atom, …) |
HTTP HeadersHow to use standard or custom HTTP headers
|
HTTP protocolGeneral informations about HTTP protocol
|
HTTP Status Redirection
300 Multiple ChoicesThe 300 (Multiple Choices) status code indicates that the target resource has more than one representation, each with its own more specific identifier, and information about the alternatives is being provided so that the user (or user agent) can select a preferred representation by redirecting its request to one or more of those identifiers. In other words, the server desires that the user agent engage in reactive negotiation to select the most appropriate representation(s) for its needs.
|
301 Moved PermanentlyThis and all future requests should be directed to the given URI.
|
302 FoundCommon way of performing URL redirection. An HTTP response with this status code will additionally provide a URL in the location header field. The user agent (e.g. a web browser) is invited by a response with this code to make a second, otherwise identical, request to the new URL specified in the location field.
|
304 Not ModifiedIndicates that the resource has not been modified since the version specified by the request headers If-Modified-Since or If-None-Match. In such case, there is no need to retransmit the resource since the client still has a previously-downloaded copy. |
307 Temporary RedirectThe 307 (Temporary Redirect) status code indicates that the target resource resides temporarily under a different URI and the user agent MUST NOT change the request method if it performs an automatic redirection to that URI. Since the redirection can change over time, the client ought to continue using the original effective request URI for future requests.
|
308 Permanent RedirectThe 308 (Permanent Redirect) status code indicates that the target resource has been assigned a new permanent URI and any future references to this resource ought to use one of the enclosed URIs.
|
HTTP Status Success
200 OKStandard response for successful HTTP requests. The actual response will depend on the request method used. In a GET request, the response will contain an entity corresponding to the requested resource. In a POST request, the response will contain an entity describing or containing the result of the action.
|
201 CreatedThe request has been fulfilled, resulting in the creation of a new resource.
|
202 AcceptedThe request has been accepted for processing, but the processing has not been completed. The request might or might not be eventually acted upon, and may be disallowed when processing occurs.
|
203 Non-Authoritative InformationThe 203 (Non-Authoritative Information) status code indicates that the request was successful but the enclosed payload has been modified from that of the origin server’s 200 (OK) response by a transforming proxy.
|
204 No ContentThe server successfully processed the request and is not returning any content.
|
206 Partial ContentThe server is delivering only part of the resource (byte serving) due to a range header sent by the client. The range header is used by HTTP clients to enable resuming of interrupted downloads, or split a download into multiple simultaneous streams.
|
HTTP Status User Error
400 Bad RequestThe server cannot or will not process the request due to an apparent client error (e.g., malformed request syntax, too large size, invalid request message framing, or deceptive request routing).
|
404 Not FoundThe requested resource could not be found but may be available in the future. Subsequent requests by the client are permissible.
|
406 Not AcceptableThe requested resource is capable of generating only content not acceptable according to the Accept headers sent in the request.
|
409 ConflictIndicates that the request could not be processed because of conflict in the request, such as an edit conflict between multiple simultaneous updates.
|
410 GoneIndicates that the resource requested is no longer available and will not be available again. This should be used when a resource has been intentionally removed and the resource should be purged. Upon receiving a 410 status code, the client should not request the resource in the future. Clients such as search engines should remove the resource from their indices. Most use cases do not require clients and search engines to purge the resource, and a 404 Not Found may be used instead.
|
412 Precondition FailedThe server does not meet one of the preconditions that the requester put on the request.
|
415 Unsupported Media TypeThe request entity has a media type which the server or resource does not support. For example, the client uploads an image as image/svg+xml, but the server requires that images use a different format.
|
428 Precondition RequiredThe origin server requires the request to be conditional. Intended to prevent the lost update problem, where a client GETs a resource’s state, modifies it, and PUTs it back to the server, when meanwhile a third party has modified the state on the server, leading to a conflict.
|
429 Too Many RequestsThe user has sent too many requests in a given amount of time. Intended for use with rate-limiting schemes.
|
Hypermedia
Hypermedia (read)How to use hypermedia to read data
|
HypermediaHow to use hypermedia
|
Miscellaneous
DocumentationHow to produce and/or propose API documentation |
Query parametersHow to use query parameters |
Performance and bandwidthHow to deal with high traffic or consumers with low bandwith |
Rate limitingHow to provide information about how many calls a consumer can do
|
Resources
Track changeHow to track change on resources
|
Create resourceHow to create resources |
Delete resourceHow to delete resources |
Resource IDWhat is a resource ID and/or how it’s built
|
RelationshipsHow to define and use relations between resources |
Dereference RelationshipsHow to load a resource and its linked resources in one call
|
Retrieve resource partiallyHow to retrieve partially a resource
|
Retrieve resourceHow to retrieve a resource |
Update resource partiallyHow to udate partially a resource |
Update resourceHow to update a resource |
URL formatHow to design URLs |
ResourceGeneral informations about resources |