Microsoft has published its Microsoft REST API Guidelines 2.3. The Guidelines serve as a design principle that urges development of resources available through a RESTful HTTP interface. The company believes "REST APIs SHOULD follow consistent design guidelines to make using them easy and intuitive." Microsoft aims to achieve five goals with the Guidelines:
- Define consistent practices and patterns for all REST endpoints across Microsoft.
- Adhere as closely as possible to accepted REST/HTTP best practices in the industry at-large.
- Make accessing Microsoft Services via REST interfaces easy for all application developers.
- Allow service developers to leverage the prior work of other services to implement, test and document REST endpoints defined consistently.
- Allow for partners (e.g., non-Microsoft entities) to use these guidelines for their own REST endpoint design.
The guidelines are clearly laid of in an easy-to-follow format. After a clean table of contents and introduction, Microsoft walks developers through interpretation, taxonomy, client guidance, 7 REST consistency fundamentals, CORS, collections, delta queries, versioning, long running operations, push notifications via webhooks, unsupported requests, and an appendix.
For those new to RESTful design, Microsoft suggests some introductory reading (RFC 2616, REST in Practice, and REST on Wikipedia). While the Guidelines apply to any publicly exposed Microsoft REST API, Microsoft also encourages third parties to follow the Guidelines. Whether the third party may need to expose its API in the future, or build a common framework across its entire environment, Microsoft preaches that the Guidelines will promote a design aspect that has become critical in the connected-economy: consistency.