Leonard Richardson - RESTful Web APIs

RESTful Web APIs

Leonard Richardson

Mike Amundsen

Sam Ruby

Beijing Cambridge Farnham Kln Sebastopol Tokyo

Praise for RESTful Web APIs

This book is the best place to start learning the essential craft of API Design.

Matt McLartyCofounder, API Academy

The entire time I read this book, I was cursing. I was cursing because as I read each explanation, I was worried that they were so good that it would be hard to find a better one to use in my own writing. You will not find another work that explores the topic so thoroughly yet explains the topic so clearly. Please, take these tools, build something fantastic, and share it with the rest of the world, okay?

Steve KlabnikAuthor, Designing Hypermedia APIs

Wonderfully thorough treatment of hypermedia formats, RESTs least well understood tenet."

Stefan TilkovREST evangelist, author, and consultant

The best practical guide to hypermedia APIs. A must-have.

Ruben VerborghSemantic hypermedia researcher

For Sienna, Dalton, and Maggie. Leonard

For Milo The Supervisor, my constant and patient companion throughout this and so many other projects. Thanks, buddy! Mike

If you purchased this ebook directly from oreilly.com, you have the following benefits:

If you purchased this ebook from another retailer, you can upgrade your ebook to take advantage of all these benefits for just $4.99. to access your ebook upgrade.

Please note that upgrade offers are not available from sample content.

Progressive Disclosure is a concept in User Interface Design whichadvocates only presenting to the user the information they need whenthey need it. In many ways, the book you are reading right now is anexample of this principle. In fact, it is quite likely that this bookwouldnt have worked a mere seven years ago.

For you see, the programming world was quite a different place when RESTful Web Services , the predecessor of this book, was written. Atthat time, the term REST was was rarely used. And when it was used itwas often misapplied, and widely misunderstood.

This was the case despite the fact that the standards upon which REST isbased, namely HTTP and HTML, were developed and became IETF and W3Cstandards in roughly their current form in the second half of the 1990s. Roy Fieldings thesis paper in which he introduced the term REST and onwhich this book was based was itself published in 2000.

Leonard Richardson and I set out to correct this injustice. To do this,we focused primarily on the concepts underpinning HTTP, and we providedpractical guidance on how to apply those concepts to applications.

Id like to think that we helped kick a few pebbles loose that startedthe avalanche of support for REST that came forth since that time. RESTrapidly took on a life of its own, and in the process has become abuzzword. In fact it now is pretty much the case that presenting a webinterface and calling it REST is practically the default. Wevedefinitely come a long way in a few short years.

Admittedly, REST as a term is often over applied, and not alwayscorrectly. But all things considered, I am very pleased that theconcepts of resources and URIs have successfully managed to infiltratetheir way into application interface design. The web, after all, is aresilient place, and these new interfaces, albeit imperfect, are leapsand bounds better than the ones that they replace.

But we can do better.

Now that those building blocks are in place, it is time to take a step back,survey the territory, and build on top of these concepts. The nextlogical step is to explore media types in general, and hypermediaformats in specific. While the first book focused almost exclusively onthe correct application of HTTP, it is time to delve more deeply intothe concepts behind hypertext media types like HTMLmedia typesthat arent tightly bound to a single application or even a single vendor.

HTML remains a prime example of a such a hypermedia format, andit continues to hold a special place in web architecture. In fact, mypersonal journey of discovery has been to take a deep dive intodevelopment of the W3C standard for HTML, now branded as HTML5. Andwhile HTML does have a prominent place in this new book, there is somuch more to cover on the topic of hypermedia. So while I have remained intouch, Leonard picked up a capable replacement for my role as coauthorin Mike Amundsen.

It has been a pleasure to watch this book be written, and in readingthis book Ive learned about a number of media types that I had not beenexposed to by any other source. More importantly, this book shows whatthese types have in common, and how to differentiate them, as each hasits own specialty.

Hopefully the pebbles that this book kicks loose will have the sameeffect as its predecessor did. Who knows, perhaps in another sevenyears it will be time to do this all over again, and highlight someother facet of Representational State Transfer that continues to beunder-appreciated.

Most software systems are created with the implicit assumption thatthe entire system is under the control of one entity, or at least thatall entities participating within a system are acting towards a commongoal and not at cross-purposes. Such an assumption cannot be safelymade when the system runs openly on the Internet.

Roy FieldingArchitectural Styles and the Design of Network-based Software Architectures

A Discordian Shall Always use the Official Discordian DocumentNumbering System.

Malaclypse the Younger and Lord Omar Khayyam RavenhurstPrincipia Discordia

Im going to show you a better way to do distributed computing, usingthe ideas underlying the most successful distributed system inhistory: the World Wide Web. I hope youll read this book if youvedecided (or your manager has decided) that your company needs topublish a web API. It doesnt matter whether youre planning a publicAPI, a purely internal API, or an API accessible by trusted partnersthey can all benefit from the philosophy of REST.

This is not necessarily the book for you if you want to learn how towrite API clients . Thats because most existing API designs arebased on assumptions that are several years old, assumptions that Idlike to destroy.

Most of todays APIs have a big problem: once deployed, they cantchange. There are big-name APIs that stay static for years at a time,as the industry changes around them, because changing them would betoo difficult.

But RESTful architectures are designed for managing change. The WorldWide Web is made of millions of websites, running atop thousands ofdifferent server implementations, and undergoing periodicredesigns. Websites are accessed by billions of users who are usinghundreds of different client implementations on dozens of hardwareplatforms. Your deployment wont look like this howling mess, but thecloser you come to web scale, the more familiar this picture willlook.

A very simple system is always easy to change. At small scales, aRESTful system has a larger up-front design cost than a push-buttonsolution. But as your API matures and starts to change, youll really need some waylike RESTof adapting to change.