The vast majority of APIs that I have come across claim to be RESTful, and in fact don’t just take my word for it the ProgrammableWeb report that 82% of their registered APIs have a RESTful architectural style. However Roy Fielding who is one of the principal authors of the HTTP specification and the originator of the Representational State Transfer suggests that an API cannot be Restful if it is not hypertext driven, he evens go so far as to say that
“Is there some broken manual somewhere that needs to be fixed?”
As he wrote the definition his words should carry slightly more weight than mine. In my experience most APIs have reached Level 2 of the Richardson Maturity model, in that they have well defined resources and use HTTP verbs for all interactions. They resemble a typical CRUD database interface, with Create, Read, Update and Delete methods for keeping records current and permanent, as they link very neatly to the interacting with resources through HTTP verbs Post, Get, Put and Delete. Whereas the RESTful architectural style is supposed to represent resource state change, and defines hypertext driven style as a requirement.
Richardson Maturity Levels
- Level 1 – Resources
- tackles the question of handling complexity by using divide and conquer, breaking a large service endpoint down into multiple resources.
- Level 2 – HTTP Verbs
- introduces a standard set of verbs so that we handle similar situations in the same way, removing unnecessary variation.
- Level 3 - Hypermedia Controls
- introduces discoverability, providing a way of making a protocol more self-documenting.
So what is a hypertext driven API and why should you care? It is often referred to as a hypermedia API and the responses will contain links that will guide the consumer/client to state transitions of the resource. When you read about hypermedia you will come across the acronym HATEOAS, which means hypermedia as the engine of application state.
There are several public hypermedia APIs out in the wild as the API Evangelist would say, if you want to see Hypermedia done well have a look at TVMaze API or the Amazon API Gateway definition that is well documented by Kin Lane himself. I also heard it well described by Mike Stowe from RingCentral, where he discusses how Hypermedia provides context, flexibility and discoverability to APIs, and his slides includes some simple examples to prove his point. I really like Mike’s slides as he represents the embedded links really well and shows the state changes of the resource.
Does it matter that an API claiming to be RESTful, does not satisfy Roy Fielding’s definition? Well I think it is important to use hypermedia and aim for Level 3 of Richardson’s maturity when it is appropriate as it does provide value. It is more than just including links in your API responses I think it makes it possible to discover and use APIs programmatically which is part of the cool thing about APIs, isn’t it? I also like how it helps to decouple the client from the server, and hides the internal system complexity from the client. It makes it easier for clients to consume resources that can be represented as links to important states and information rather than dumping the resource details in the response and expecting the client to make sense of it all. I will leave the final word to Dovel Technologies who also had a look at this subject and includes the following statement:
What so many techies lose sight of is the fact that REST isn’t supposed to make the Web more like system integration; it’s meant to make system integration more like the Web