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 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
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.
URI Templates and forms were generally
suggested to expose parameters for resources.
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.
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.
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.
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