RESTful Web APIs is the follow-up book to RESTful Web Services and is an updated view on how to build a truly RESTful service. It was published in late 2013 so has the benefit of a few years of hindsight compared to the original book, and it is written by one of the original authors, Leonard Richardson. I [wrote down some thoughts on the original book]({% post_url 2015-02-06-restful-web-services-book %}) and wanted to see what this “sequel” had to offer.
There are a number of insightful ideas and the authors try to be pragmatic. Personally, I think it is difficult to build a truly RESTful service with hypermedia but the book gives several ideas and exercises on how to build one.
Forget Resource-Oriented Architecture
While RESTful Web Services introduced Resource-Oriented Architecture (ROA), RESTful Web APIs basically casts the methodology aside. Today, most APIs use the uniform interface (GET, POST, PUT, DELETE), status codes, and can support multiple representations of resources (JSON, XML, etc.) with various degrees of success. However, the book poses the idea that it is the hypermedia part that is missing and yet is the most powerful concept in RESTful architectures.
Hypermedia is what distinctly separates RESTful architectures from RPC/SOAP-based ones. It is what makes the web “work” without versioning and without having to learn rules for visiting each website.
You don’t know or care that you’re visiting revision 1.0 or revision 2500 of a website. You just browse it. And when you browse a website, you do not have to construct URLs based on some convention or figure out what parameters are available. There are hyperlinks and forms to guide you. For those that like poor acronyms, HATEOS is the concept missing from today’s RESTful APIs.
The book proposes a change in mindset from resource-based designs to designs based on states (representations) and transitions (links) between states.
Random Thoughts
PATCH for update
Instead of PUT, use PATCH for updates. Some frameworks such as Ruby on Rails have wholeheartedly made this change. The only controversial part is perhaps the lack of widespread support for this addition to the standard HTTP methods (whether it be in proxies, frameworks, etc.).
JSON-Patch and an RFC for XML patching are suggested for partial updates.
How to Represent Dynamic Resources as Hypermedia
URI Templates and forms were generally suggested to expose parameters for resources.
Collection+JSON was also shown as a possible hypermedia format to represent collections of items and to present the templates and forms. The book still referred to Atom for some use cases but Atom seems to increasingly lack usage. I actually would have liked some form of Atom to remain in usage because other standards like PubSubHubBub seemed to provide a more realtime (using webhooks yet more efficient) web.
Versioning
One of the ideas is that the need for versioning is not as important with hypermedia providing part of the solution. Unfortunately, the book and I believe we are a ways off from clients automatically understanding the semantics behind the data. Unlike most programmed API clients, web browsers have a person deciding which links to click on the web.
Due to the lack of smarter clients, APIs may have to be versioned when breaking changes are made. The book provides a few non-hypermedia possible solutions for versioning an API that are commonly used (e.g. version in path). The book makes an interesting case when hypermedia can definitely help but until we have clients that are programmed to take advantage of the hypermedia, it may be difficult to solely rely on hypermedia to prevent breaking API clients.
Better References
The book lists a number of resources, hypermedia standards, ways to register your media type, ways to register your link relations, etc. as examples. It also gave some quick information about each.
While hypermedia perhaps still isn’t an essential component of some RESTful APIs, there seems to be an upswing in adoption of forms of hypermedia. I don’t recall it mentioned in the book but the GitHub API seems to be adopting hypermedia. I used to refer to the Twitter API as one of the better examples of a practical RESTful API but it seems GitHub’s API is better.
Conclusion
Overall the book was a healthy read. While it mainly focused on hypermedia, it provided several good thought exercises on how to design a better RESTful API using hypermedia. Most API designers/implementors would probably get more out of RESTful Web APIs today than RESTful Web Services just due to the advancement of general understanding of RESTful architectures.