BT

Facilitating the Spread of Knowledge and Innovation in Professional Software Development

Write for InfoQ

Topics

Choose your language

InfoQ Homepage News Microsoft REST API Guidelines Are Not RESTful

Microsoft REST API Guidelines Are Not RESTful

This item in japanese

Bookmarks

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.

Rate this Article

Adoption
Style

Hello stranger!

You need to Register an InfoQ account or or login to post comments. But there's so much more behind being registered.

Get the most out of the InfoQ experience.

Allowed html: a,b,br,blockquote,i,li,pre,u,ul,p

Community comments

  • Yea, color me shocked

    by Will Hartung,

    Your message is awaiting moderation. Thank you for participating in the discussion.

    I stopped my crusade long ago, as the World has usurped REST for HTTP. REST is almost meaningless as a descriptor today. Well, I should say, REST as a descriptor for it original intent is almost meaningless today. It's overwhelmed by, essentially, REST == HTTP.

    I used to actively remove REST tags from Stack Overflow questions that clearly had nothing to do with REST, but the task was simply too daunting.

    To be clear, and to be fair, I'm not a staunch practitioner of REST, within my projects, etc. I'm as lazy as the next guy in not going the extra mile when all I need to do is stuff a remote message over a socket via HTTP, but that doesn't mean I don't respect the work, and the message, and care to not see it subverted.

  • Re: Yea, color me shocked

    by Dan Haywood,

    Your message is awaiting moderation. Thank you for participating in the discussion.

    +1, REST is pretty much meaningless. Fwiw, I prefer to use the term "hypermedia" API these days, a far higher bar to hit than just using HTTP.

  • Do we really care?

    by Monkey D. Luffy,

    Your message is awaiting moderation. Thank you for participating in the discussion.

    As long as it works for the team and their services can talk to each other, how much should we care about REST?

  • That's because microsoft have different target to constuct with Roy

    by yang sunny,

    Your message is awaiting moderation. Thank you for participating in the discussion.

    Roy Fielding's target is whole WWW,but we target is point 2 point. we should construct out application with all the whole www's features?

  • Re: Do we really care?

    by Stephen Anderson,

    Your message is awaiting moderation. Thank you for participating in the discussion.

    Because if you don't implement REST fully, you don't get all the architectural benefits. Each one of the REST constraints gives you some benefit. Also, we're software professionals, precision in terminology is supposed to be important to us :)

  • Re: That's because microsoft have different target to constuct with Roy

    by Will Hartung,

    Your message is awaiting moderation. Thank you for participating in the discussion.

    Nobody cares what you do, just don't call it what it isn't. REST has a specific definition, and this stuff isn't it. There's no REST quacking, REST walking, or REST looking here. It's not REST. Simple.

    So, don't call it that.

  • Definitions change

    by Tibor Jakab,

    Your message is awaiting moderation. Thank you for participating in the discussion.

    This is especially true in software. REST had a definition 16 years ago but the masses didn't adopt that, there are very few APIs on the market today what are truly RESTful. People (even senior developers) call RESTful anything what works over HTTP and has a somewhat nice URL. Many have no clue about what REST really is, and often they don't even use HTTP verbs. Is this wrong? From REST author's point of view is definitely wrong, but now is too late to overturn the masses who use the term REST for something else than it was originally created for.

  • Roy's bleating misses the point

    by Paul Beckford,

    Your message is awaiting moderation. Thank you for participating in the discussion.

    Roys dissertation discusses architectural styles, and details an architectural style suited to the world wide web which he calls REST.

    Now in his own terms an architectural style is a set of design constraints, which lend themselves well to a particular application domain.

    If your application provides an interface to an intelligent agent (a human) who wants to navigate, read and/or modify a distributed web of resources then REST is likely to be right up your street.

    The problem is though, that such applications are few and far between. The Web as we know it, with web browsers, servers and all the network infrastructure in between is (almost) one such example. RSS feed readers are another.

    For the vast majority of developers out there, this isn't what they want. What they want is an architectural style that is well suited to building distributed services. Services are not resources, although with a little bit of effort you can make them look like a bunch of resources, sort of, nonetheless they are not the same thing.

    So what people do is kludge REST to suite the problem at hand, which invariably means breaking some design constraint or the other. No surprise because the REST style was never formulated to facilitate services in the first place.

    Alan Kay in his 1997 OOPSLA keynote speech describes the world wide web as what you get when you allow physicists to write software, and I think he has a point. The web has a very narrow application. If you want something more general purpose you really should look elsewhere.

    Alan described a world of distributed objects, which was general purpose and well suited to the idea of services, but this never saw the light of day (an know he didn't mean CORBA or COM, which are both bastardisations of this idea built on a false premise).

    So pragmatically, programmers are doing what they have always done, knocking together solutions, from what ever ubiquitous tools they have at hand, producing solutions that are good enough. If this means breaking REST purity then so be it.

    If this make Roy uncomfortable, one response would be to come up with a more general purpose architectural style, one that addresses their needs. As far as I can tell, he or no one else has done this.

  • Re: Roy's bleating misses the point

    by Will Hartung,

    Your message is awaiting moderation. Thank you for participating in the discussion.

    You're suggesting that Roy change his definition of the architecture that he has discussed and documented because the people today misuse the term. That Roy is wrong, not the people that co-opt and misuse it.

    When someone builds a stuccoed tract home, filled with carpet, drywall, and linoleum, and calls it a "Craftsman style house", that's the fault of Morris and the others who founded the Arts and Crafts movement, not the fact that the builder just put in some token oak trim and that alone is what qualified it as a Craftsman style home. Yea, that doesn't sound right either, does it?

    So, no, what make Roy uncomfortable is folks misusing the architecture that he named and promoted. The onus is not on him to change his paper or terms or definition to suit the corruptors.

  • Re: Roy's bleating misses the point

    by Paul Beckford,

    Your message is awaiting moderation. Thank you for participating in the discussion.

    You're suggesting that Roy change his definition of the architecture that he has discussed and documented because the people today misuse the term.


    No, I've said no such thing. I am saying that the architecture he has documented is not ideally suited to the purpose to which it is commonly applied (distributed services). I find it odd that he never addresses this real issue.

    I agree with him that most so called RESTful services aren't truly REST. I am saying that the reason why is because a strict interpretation of REST is only applicable to a narrow set of applications and cannot be considered a general purpose solution to distributed software services.

Allowed html: a,b,br,blockquote,i,li,pre,u,ul,p

Allowed html: a,b,br,blockquote,i,li,pre,u,ul,p

BT