Microsoft has published their guidance for creating “RESTful” APIs. Roy Fielding calls them HTTP APIs that have little to do with REST.
Many organizations have published their recommendations for creating HTTP APIs for the web. Even the US White House has published a standard at White House Web API Standards. Microsoft has recently made public their Microsoft REST API Guidelines 2.3, a thorough and mature specification. The guidelines have been developed and are used mainly by the Azure teams in their work building cloud services.
We are summarizing here a few key points from Microsoft’s API guidelines, leaving the complete lecture of the document to the concerned reader:
- URLs should be readable and constructible by humans to facilitate the adoption of such APIs without the need of a client library.
- The following HTTP verbs are supported: GET, PUT, DELETE, POST, HEAD, PATCH, OPTIONS. Not all resources should support all verbs.
- GET, PUT, DELETE and HEAD should be idempotent.
- Custom headers must not be required.
- Clients should not be required to transmit personally identifiable information parameters in the URL because they might be exposed through log files. The parameters should be passed through headers.
- Data should be provided in popular formats.
- The default data encoding is JSON.
- “Primitive values MUST be serialized to JSON following the rules of RFC4627.”
- Developers using the APIs should be able to use the language and platform of preference.
- Services should be accessible even from simple HTTP tools such as curl.
- APIs should support explicit versioning.
- Services should be stable without introducing breaking changes if possible, but they should be allowed to do so if necessary, incrementing the version number to signal that.
- Versioning should be done using a Major.Minor scheme.
- Services may implement push notifications via web hooks (HTTP Callbacks).
The guidelines provide an example of what is considered to be a well-structured URL,
https://api.contoso.com/v1.0/people/jdoe@contoso.com/inbox
and another example of a URL that should be avoided:
https://api.contoso.com/EWS/OData/Users('jdoe@microsoft.com')/Folders('…[very long identifier]…=')
Shortly after the Microsoft guidelines for REST APIs went public, Roy Fielding, author of REST, HTTP/1.1 and co-founder of the Apache Foundation, has expressed his dissatisfaction with it: “even my worst description of REST is way better than the summary or references given in [Microsoft/api-guidelines].” InfoQ has reached out to Fielding to find out more details on why he is not happy with the guidelines. We publish his reply in full:
I think it is great that companies like Microsoft have decided to publish some of their internal documentation and development guidelines on public forums, especially within open collaboration spaces like GitHub. This openness to public conversations will significantly improve how we all work within this industry.
What I dislike about these guidelines is that they are a compilation about how one might develop reasonable HTTP APIs within the Microsoft ecosystem, but is labelled as being REST and RESTful APIs. REST != HTTP, as is obvious from a cursory read of any of the relevant materials about REST. The guidelines are clearly not based on REST and don't even manage to reference my work (aside from the parts of RFC2616 that have been obsoleted by RFC7231). This is a common mistake by folks who were formerly deep in the Web Services world: to describe
REST as some sort of HTTP version of a SOAP/RPC interface.No matter how common that mistake is in practice, it cannot pretend to be REST. Most of the properties of the REST architectural style come from adhering to all of its constraints, not just those that are conveniently similar to failed tools of the past. I have no problem with folks who only want to build RPC interfaces using HTTP, provided they call them HTTP APIs. They are not REST. They are not of the Web. That doesn't mean they can't be honestly described and implemented as HTTP services. It is worthwhile to understand them as such, and to discuss their implementation guidelines without feeling a need for mistaken buzzword compliance.
Many web service providers are creating HTTP APIs and are very successful in using them. Most of cloud computing is based on such APIs. It is still a mystery why so many insist to label them as “RESTful” when they are not. For those interested in reading more about this issue, we recommend the following InfoQ articles: Why Some Web APIs Are Not RESTful and What Can Be Done About It, Roy Fielding on Versioning, Hypermedia, and REST.