Thoughts on RESTful API Design
Red Hat
Asynchronicity
AsynchronicityHow to handle long operations |
Notifying API consumersHow to send events or notifications to API consumers |
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
Data formatwhich data format use |
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. |
OPTIONSThe OPTIONS method returns the HTTP methods that the server supports for the specified URL. This can be used to check the functionality of a web server by requesting ‘*’ instead of a specific resource. |
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. |
PUTThe PUT method requests that the enclosed entity be stored under the supplied URI. If the URI refers to an already existing resource, it is modified; if the URI does not point to an existing resource, then the server can create the resource with that URI. |
HTTP methodsGeneral information about HTTP methods usage |
HTTP Protocol
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 Status User Error
405 Method Not AllowedA request method is not supported for the requested resource; for example, a GET request on a form which requires data to be presented via POST, or a PUT request on a read-only resource. |
Hypermedia
Hypermedia (read)How to use hypermedia to read data |
Hypermedia (write)How to use hypermedia to write data
|
HypermediaHow to use hypermedia |
Miscellaneous
DocumentationHow to produce and/or propose API documentation
|
Guiding inputsHow to help consumers or end user to input relevant data
|
Resources
Action resourceHow to use action resource (e.g. resources like /cancel or /approve) |
Create resourceHow to create resources |
Delete resourceHow to delete resources |
Resource IDWhat is a resource ID and/or how it’s built |
Update resource partiallyHow to udate partially a resource |
RelationshipsHow to define and use relations between resources |
Retrieve resourceHow to retrieve a resource |
Update resourceHow to update a resource |
URL formatHow to design URLs |
ResourceGeneral informations about resources |