Microsoft REST API Guidelines

Microsoft

API Design

Global design

General considerations on API design

API Lifecycle

Versioning

How to handle API versioning

Governance

How to ensure API governance (advertise, consistency, …)

Collection Resources

Sorting a collection

How to sort a collection of resources

Collection

What is a collection (set) of resources

Filtering

How to select some resources in a collection

Pagination

How to retrieve a range of resources in a collection

Error handling

Errors

How to handle errors

Error format

How to provide information about errors

HTTP Methods

OPTIONS

The 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.

POST

The 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.

PATCH

The PATCH method applies partial modifications to a resource.

HEAD

The 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.

HTTP methods

General information about HTTP methods usage

DELETE

The DELETE method deletes the specified resource.

GET

The GET method requests a representation of the specified resource. Requests using GET should only retrieve data and should have no other effect.

PUT

The 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 Protocol

HTTP Statuses

General information about HTTP statuses usage

HTTP Headers

How to use standard or custom HTTP headers

Content negociation and media types

How to describe your API data format and/or propose different formats (like json, yaml, xml atom, …)

HTTP protocol

General informations about HTTP protocol

Caching

How to use and provide relevant caching informations

Hypermedia

Hypermedia (read)

How to use hypermedia to read data

Miscellaneous

Documentation

How to produce and/or propose API documentation

  • Options and link headers
    In addition, services SHOULD include a Link header (see RFC 5988) to point to documentation for the resource

Developer experience

How to take care of developer experience (DX)

CORS

How to deal with CORS

Resources

Track change

How to track change on resources

Create resource with a specific ID

How to create resource with a provided id

Action resource

How to use action resource (e.g. resources like /cancel or /approve)

ID with semantic

Using meaningful ids (like me)

Resource ID

What is a resource ID and/or how it’s built

Batch Bulk

How to handle batch/bulk processing/creation/update/… (e.g. handle multiple resources at conce)

Create resource

How to create resources

Update resource partially

How to udate partially a resource

Update resource

How to update a resource

URL format

How to design URLs

Retrieve resource partially

How to retrieve partially a resource

Security

Data privacy

Data privacy concerns

Security

Security concerns