API Design Guide
Cisco
API Lifecycle
Updates and VersioningHow to handle API updates and versioning |
Collection Resources
CollectionWhat is a collection (set) of resources |
PaginationHow to retrieve a range of resources in a collection |
FilteringHow to select some resources in a collection |
Data
Data formatwhich data format use
|
Date and TimeHow to deal with date and time data
|
Null dataHow to deal with null data |
Error handling
Error formatHow to provide information about errors |
HTTP Methods
HTTP methodsGeneral information about HTTP methods usage |
GETThe GET method requests a representation of the specified resource. Requests using GET should only retrieve data and should have no other effect. |
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. |
DELETEThe DELETE method deletes the specified resource. |
PATCHThe PATCH method applies partial modifications to a resource. |
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. |
Forbidden methods alternativesWhat to do when only possible HTTP methods are POST and GET |
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 StatusesGeneral information about HTTP statuses usage |
Hypermedia
HypermediaHow to use hypermedia
|
Hypermedia (read)How to use hypermedia to read data
|
Miscellaneous
API chainingHow to chain API call in internal systems |
DocumentationHow to produce and/or propose API documentation
|
UndoHow to undo things
|
Naming
NamingHow to name things
|
CaseWhich case (lowercase, camelCase, …) to use and when |
Resources
ResourceGeneral informations about resources
|
URL formatHow to design URLs |
ID with semanticUsing meaningful ids (like |
Retrieve resourceHow to retrieve a resource |
Retrieve resource partiallyHow to retrieve partially a resource |
Dereference RelationshipsHow to load a resource and its linked resources in one call
|
Create resourceHow to create resources |
Create resource with a specific IDHow to create resource with a provided id |
Replace resourceHow to replace (or update fully) a resource |
Update resourceHow to update a resource |
Update resource partiallyHow to udate partially a resource |
Delete resourceHow to delete resources |
Batch BulkHow to handle batch/bulk processing/creation/update/… (e.g. handle multiple resources at conce) |
Action resourceHow to use action resource (e.g. resources like /cancel or /approve) |
Security
SecuritySecurity concerns
|