Microsoft is publishing its “REST API Design Guidelines” to the API community: https://www.GitHub.com/microsoft/api-guidelines/.
These guidelines represent a multi-year, cross-company, collaborative process aggregating the collective experience of hundreds of engineers designing, operating, and running global scale cloud services from across Microsoft; and listening to feedback on our APIs from customers and partners. We have attempted to incorporate those learnings along with industry best practices in the API space to create guidelines that API teams across Microsoft use on a daily basis.
Our hope in publishing these guidelines to the greater API community is twofold:
- First, that we will further stimulate feedback on our APIs and our approach to building them – only through such feedback can we build products that match the evolving needs of our customers.
- Second, as we have benefitted from others in the API design community who have shared their guidelines, we want to contribute back. We believe that organizations of almost any size building APIs can benefit from having their own design guidelines. Many companies and even organizations such as the Whitehouse have already published their design guidelines and it’s our hope that by contributing ours to the community conversation, we can add to the body of community knowledge and reusable content so that anyone can draw upon more collective knowledge when looking to set standards and guidelines within their organization.
We recognize that in API design, there are multiple correct ways to do things (ex: snake-case vs. train_case vs. UpperPascalCase vs. …) and we are sharing these design guidelines as what we have settled-upon after much debate among Microsoft colleagues. We expect that these guidelines will evolve over time and that your feedback will play a part in that evolution.
Origins
Naturally, the Microsoft REST API Guidelines document on GitHub went through a number of iterations before being what you can read today.
The effort got started from hearing two key points of feedback from customers:
- It should be easier to get started with Microsoft APIs – Developers wanted to be able to run the curl tool against an API endpoint and get a human-readable result in just a few minutes
- APIs for Microsoft cloud services should be consistent – Developers didn’t care that an API to work with an Azure virtual machine and an API to work with a user’s Office 365 documents were developed by different parts of the company, they were both from Microsoft and developers expected consistency.
One of the goals of the effort was to find the right balance of detail in the guidelines. We wanted a document that sufficiently codified best practices, but was also approachable for individual contributor engineers and technical product/program managers.
Relationship with OData
The OASIS Open OData standard provides a great level of detail for API developers seeking wire-level interoperability; and while Microsoft teams are encouraged to follow OData (and benefit from the broad OData ecosystem), there are some cases where it was more specificity than teams needed and some cases where additional information was needed. For any areas of deviation, we have worked to feed information back to the OASIS OData Technical Committee and many aspects of the latest OData v4.0 and OData v4.01 incorporate learnings from evolution of the Microsoft REST API Guidelines.
Relationship with the Open API Initiative (OAI)
We are proud that Microsoft is a member of the Open API Initiative (OAI), the evolution of Swagger. As the scope of OAI/Swagger efforts have expanded from a framework and tooling to also include a specification, we believe there are more opportunities ahead for Microsoft colleagues to engage with the OAI community to continue to evolve both.
