Microsoft Publishes REST API Guidelines 2.3

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.
As a tech behemoth, Microsoft serves and supports a massive client base. Given the diversity of its client base, Microsoft cannot afford to isolate its clients through the use of rich frameworks. And although Microsoft publishes a number of language-specific frameworks, REST operations over HTTP sit at the heart of its entire portfolio. This consistent, basic framework provides for a simple and consistent framework that clients across the board can integrate with. 

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. 

Be sure to read the next API Design article: Why Consistency Matters Across the Media Types Offered by an API


Comments (0)