Microsoft REST API Guidelines
Microsoft
API Design
Global designGeneral considerations on API design |
API Lifecycle
GovernanceHow to ensure API governance (advertise, consistency, …) |
Updates and VersioningHow to handle API updates and versioning |
Asynchronicity
AsynchronicityHow to handle long operations |
Notifying API consumersHow to send events or notifications to API consumers |
Collection Resources
FilteringHow to select some resources in a collection |
PaginationHow to retrieve a range of resources in a collection |
Sorting a collectionHow to sort a collection of resources |
CollectionWhat is a collection (set) of resources |
Data
Date and TimeHow to deal with date and time data |
Data formatwhich data format use |
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. |
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
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 |
HTTP protocolGeneral informations about HTTP protocol |
Hypermedia
Hypermedia (read)How to use hypermedia to read data
|
Miscellaneous
CORSHow to deal with CORS |
Developer experienceHow to take care of developer experience (DX) |
DocumentationHow to produce and/or propose API documentation
|
Resources
Action resourceHow to use action resource (e.g. resources like /cancel or /approve) |
Track changeHow to track change on resources |
Create resource with a specific IDHow to create resource with a provided id |
Create resourceHow to create resources |
ID with semanticUsing meaningful ids (like |
Resource IDWhat is a resource ID and/or how it’s built |
Batch BulkHow to handle batch/bulk processing/creation/update/… (e.g. handle multiple resources at conce) |
Retrieve resource partiallyHow to retrieve partially a resource
|
Update resource partiallyHow to udate partially a resource |
Update resourceHow to update a resource |
URL formatHow to design URLs |
Security
SecuritySecurity concerns |
Data privacyData privacy concerns |