If you ever build a REST(like) service, you know that there is no one ‘right’ way to build such a service. Okey, you have the HTTP specs and the REST dissertation by Roy Fielding but this still keeps a lot of questions unanswered:
- How do you handle versioning?
- When do you use which HTTP status code?
- What metadata do you add to your headers?
- How do you return error data?
- …
In an effort to structurize all REST services build by Microsoft in the same way, they made their REST API guidelines publicly available:
The Microsoft REST API Guidelines, as a design principle, encourages application developers to have resources accessible to them via a RESTful HTTP interface. To provide the smoothest possible experience for developers on platforms following the Microsoft REST API Guidelines, REST APIs SHOULD follow consistent design guidelines to make using them easy and intuitive.
This document establishes the guidelines Microsoft REST APIs SHOULD follow so RESTful interfaces are developed consistently.
If you have to decide on your own standards to use inside your organization or you want to consume a Microsoft REST service, this guide is certainly worth a look.
Content:
- 1 ABSTRACT
- 2 TABLE OF CONTENTS
- 3 INTRODUCTION
- 4 INTERPRETING THE GUIDELINES
- 5 TAXONOMY
- 6 CLIENT GUIDANCE
- 7 REST CONSISTENCY FUNDAMENTALS
- 8 CORS
- 9 COLLECTIONS
- 10 DELTA QUERIES
- 11 JSON STANDARDIZATIONS
- 12 VERSIONING
- 13 LONG RUNNING OPERATIONS
- 14 PUSH NOTIFICATIONS VIA WEBHOOKS
- 15 UNSUPPORTED REQUESTS
- 16 APPENDIX