What's New in RESTful Web APIs?

I was asked on Twitter what changed between 2007's RESTful Web Services and 2013's RESTful Web APIs. I've covered this in a couple old blog posts but here's my definitive explanation.

First, let me make it super clear that there is no longer any need
to buy Services. It's out of date and you can
legitimately get it for free on the Internet. O'Reilly is taking Services out of print, but there's going to be a transition period in which copies of the old
book sit beside copies of the new book in Barnes & Noble. Don't buy the old one. The bookstore will eventually send it back and it'll get deducted from my royalties. If you do buy Services by accident, return it.

If you're not specifically interested in the difference between the
old book and the new one, I'd recommend looking at RESTful Web
APIs's chapter-by-chapter description to see if RESTful Web APIs is a book you want. As to the differences, though, in my mind there are
three big ones:



The old book never explicitly tackles the issue of
designing hypermedia documents that are also valid JSON. That's because JSON
didn't become the dominant API document format until after the
book was published. If you don't know that's going to happen, JSON
looks pretty pathetic. It has no hypermedia capabilities! And yet,
here we are.

In my opinion, a book that doesn't tackle this issue is propping up
the broken status quo. RESTful Web APIs starts hammering this
issue in Chapter 2 and doesn't let up.

There are a ton of new technologies designed to get us out of the
JSON trap (Collection+JSON, Siren, HAL, JSON-LD, etc.) but the old book doesn't cover those
technologies, because they were invented after the book was
published. RESTful Web APIs covers them.

New ideas in development will, I hope, keep moving
the field forward even after we all get on board with hypermedia. I'm
talking about profiles. Or some other idea similar to profiles,
whatever. These ideas are pretty cutting edge today, and they were
almost inconceivable back in 2007. RESTful Web APIs covers
them as best it can.

Now, for details. Services was heavily focused
on the HTTP notion of a "resource." Despite the copious client-side
code, this put the focus clearly on the server side, where the
resource implementations live. RESTful Web APIs focuses on
representations—on the documents sent back and forth between
client and server, which is where REST lives.

The introductory story from the old book is still
present. Web APIs work on the same principles as the Web, here's how
HTTP works, here's what the Fielding constraints do, and so on. But
it's been rewritten to always focus on the interaction, on the client
and server manipulating each others' state by sending representations
back and forth. By the time we get to Chapter 4 there's also a
pervasive focus on hypermedia, which is the best way to for the server
to tell the client which HTTP requests it can make next.

This up-front focus on hypermedia forces us to deal with
hypermedia-in-JSON (#1), using the tools developed since 2007
(#2). The main new concept in play is the "collection pattern". This
is the CRUD-like design pioneered by the Atom Publishing Protocol, in
which certain resources are "items" that respond to GET/PUT/DELETE,
and other resources are "collections" which contain items and respond
to POST-to-append.

We covered AtomPub in Services, but over the
past six years it has become a design pattern, reinvented (I think
"copied" is too strong a word) thousands of times.

RESTful Web APIs focused heavily on the collection pattern,
without ever naming it as a pattern. I'm not dissing this pattern; it's very useful. I'd estimate about eighty percent of "REST" APIs can
be subsumed into the collection pattern. But REST is bigger than the
collection pattern. By naming and defining the collection pattern, we
gain the ability to look at what lies beyond.

Attempts to encapsulate the collection pattern include two new
JSON-based media types: Collection+JSON and OData. The collection
pattern also shows up, more subtly, in the Siren and Hydra
formats. Which brings me to the second major change.

In 2007, there were two big hypermedia formats: Atom and HTML. Now
there are a ton of hypermedia formats! This is great, but it's also
confusing. In "The Hypermedia Zoo", Chapter 10 of RESTful Web
APIs, we give an overview of about two dozen hypermedia
formats. The ones we seriously recommend for general use (HAL, Siren,
HTML, JSON-LD, etc.) are covered in more detail elsewhere in the
book. The quirkier, more specialized media types just get an exhibit
in the zoo.

Now for the third new thing, profiles. If you go through the
RESTful Web APIs narrative from Chapter 1 to Chapter 7, you'll
see that we introduce a problem we're not able to solve. Hypermedia
is great at solving the following problem:

How is an API client supposed to understand what
HTTP requests it might want to make next?

But there's a superficially similar problem that hypermedia can't
solve:

How is an API client supposed to understand what will
happen in real-world terms if it makes a certain HTTP request?

How do you explain the real-world semantics of an HTTP state
transition? Before chapter 8, the two solutions are to do it ahead of
time in one-off human-readable documentation; or to define a
domain-specific media type, a la Maze+XML. Both of these approaches
have big problems. Chapter 8 introduces profiles, which lets you get some of the benefits of a new media type without doing unnecessary work.

Maybe profiles will turn out not to be the right answer, but we
gotta solve this problem somehow, and the old book is
not equipped to even formulate the problem.

There are also a few additions to the book I consider
minor. There's a whole chapter in RESTful Web APIs on Semantic
Web/Linked Data stuff; in Services there was nothing but a
cursory discussion of RDF/XML as a representation format. There's a
chapter in RESTful Web APIs about CoAP, which didn't exist in
2007. These are good chapters that took me a long time to write, but I
don't think it's worth buying the book if you only want to read the
chapter on CoAP. (Or maybe it is! There's not a lot of competition
right now.)

So, what hasn't changed? HTTP hasn't changed all that
much. RESTful Web APIs's information about HTTP has been brought up to date but not changed significantly. So if you were using Services solely as an API-flavored HTTP reference, you don't need the new book. You can just read up on the protocol-level
additions to HTTP since 2007, like the Link header and
standardized patch formats for PATCH.

Hopefully this helps! RESTful Web APIs has a lot of distinguished competition that the old book didn't have, but its competition is newer books like Designing Hypermedia APIs and REST in Practice. If you compare APIs to Services I think it's no contest.