Microsoft has made REST API Design Guidelines available to developers through the API community. The new guidelines are available from GitHub here and at the source. Among other reasons, Microsoft says the guidelines are in place to give developers easier access to Microsoft Services via REST.
The company’s Cloud Platform resources are mostly accessed through RESTful HTTP interfaces. Developers can wrap APIs in language frameworks in each service, but operations within services are mostly REST API over HTTP.
Microsoft says this limited framework is simply because it supplies support to so many clients with different needs. Instead of creating multiple frameworks dependent on service, it is easier to use a single framework.
Creating the guidelines means all developers can have an easy way of using REST APIs with simple HTTP support. Microsoft says making the REST APIs follow “consistent design guidelines” is essential for having the most workable environment for developers. The guidelines help users understand how to make RESTful interfaces easily.
Reasons for Guidelines
In the introduction to the guidelines, the company points out why it decided to make the document:
“These guidelines aim to achieve the following:
- 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 document is lengthy, so we suggest getting the coffee on and preparing for a long read. However, if you are a developer on Microsoft’s Cloud Platform then it is also an essential read.
