Microsoft REST API guidelines

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:

MICROSOFT REST API GUIDELINES

• 1 ABSTRACT
• 2 TABLE OF CONTENTS
• 3 INTRODUCTION
  • 3.1 RECOMMENDED READING
• 4 INTERPRETING THE GUIDELINES
  • 4.1 APPLICATION OF THE GUIDELINES
  • 4.2 GUIDELINES FOR EXISTING SERVICES AND VERSIONING OF SERVICES
  • 4.3 REQUIREMENTS LANGUAGE
  • 4.4 LICENSE
• 5 TAXONOMY
  • 5.1 ERRORS
  • 5.2 FAULTS
  • 5.3 LATENCY
  • 5.4 TIME TO COMPLETE
  • 5.5 LONG RUNNING API FAULTS
• 6 CLIENT GUIDANCE
  • 6.1 IGNORE RULE
  • 6.2 VARIABLE ORDER RULE
  • 6.3 SILENT FAIL RULE
• 7 REST CONSISTENCY FUNDAMENTALS
  • 7.1 URL STRUCTURE
  • 7.2 URL LENGTH
  • 7.3 CANONICAL IDENTIFIER
  • 7.4 SUPPORTED VERBS
  • 7.5 STANDARD REQUEST HEADERS
  • 7.6 STANDARD RESPONSE HEADERS
  • 7.7 CUSTOM HEADERS
  • 7.8 SPECIFYING HEADERS AS QUERY PARAMETERS
  • 7.9 PII PARAMETERS
  • 7.10 RESPONSE FORMATS
  • 7.11 HTTP STATUS CODES
  • 7.12 CLIENT LIBRARY OPTIONAL
• 8 CORS
  • 8.1 CLIENT GUIDANCE
  • 8.2 SERVICE GUIDANCE
• 9 COLLECTIONS
  • 9.1 ITEM KEYS
  • 9.2 SERIALIZATION
  • 9.3 COLLECTION URL PATTERNS
  • 9.4 BIG COLLECTIONS
  • 9.5 CHANGING COLLECTIONS
  • 9.6 SORTING COLLECTIONS
  • 9.7 FILTERING
  • 9.8 PAGINATION
  • 9.9 COMPOUND COLLECTION OPERATIONS
• 10 DELTA QUERIES
  • 10.1 DELTA LINKS
  • 10.2 ENTITY REPRESENTATION
  • 10.3 OBTAINING A DELTA LINK
  • 10.4 CONTENTS OF A DELTA LINK RESPONSE
  • 10.5 USING A DELTA LINK
• 11 JSON STANDARDIZATIONS
  • 11.1 JSON FORMATTING STANDARDIZATION FOR PRIMITIVE TYPES
  • 11.2 REST GUIDELINES FOR DATES AND TIMES
  • 11.3 JSON SERIALIZATION OF DATES AND TIMES
  • 11.4 DURATIONS
  • 11.5 INTERVALS
  • 11.6 REPEATING INTERVALS
• 12 VERSIONING
  • 12.1 VERSIONING FORMATS
  • 12.2 WHEN TO VERSION
  • 12.3 DEFINITION OF A BREAKING CHANGE
• 13 LONG RUNNING OPERATIONS
  • 13.1 RESOURCE BASED LONG RUNNING OPERATIONS (RELO)
  • 13.2 STEPWISE LONG RUNNING OPERATIONS
  • 13.3 RETENTION POLICY FOR OPERATION RESULTS
• 14 PUSH NOTIFICATIONS VIA WEBHOOKS
  • 14.1 SCOPE
  • 14.2 PRINCIPLES
  • 14.3 TYPES OF SUBSCRIPTIONS
  • 14.4 CALL SEQUENCES
  • 14.5 VERIFYING SUBSCRIPTIONS
  • 14.6 RECEIVING NOTIFICATIONS
  • 14.7 MANAGING SUBSCRIPTIONS PROGRAMMATICALLY
  • 14.8 SECURITY
• 15 UNSUPPORTED REQUESTS
  • 15.1 ESSENTIAL GUIDANCE
  • 15.2 FEATURE ALLOW LIST
• 16 APPENDIX
• 16.1 SEQUENCE DIAGRAM NOTES