RESTful Web APIs

by Leonard Richardson

The popularity of REST in recent years has led to tremendous growth in almost-RESTful APIs that don't include many of the architecture's benefits. With this practical guide, you'll learn what it takes to design usable REST APIs that evolve over time. By focusing on solutions that cross a variety of domains, this book shows you how to create powerful and secure applications, using the tools designed for the world's most successful distributed computing system: the World Wide Web. You'll explore the concepts behind REST, learn different strategies for creating hypermedia-based APIs, and then put everything together with a step-by-step guide to designing a RESTful Web API.

Genres: Programming, Technology, Computer Science, Software, Technical, Coding, Web

424 pages, Paperback

First published January 1, 2013

About the author

Leonard Richardson is an expert on RESTful API design, the developer of the popular Python library Beautiful Soup, and a science fiction novelist.

Reviews

[Vitor · Rating 3 out of 5]

The author wants to convince the web API designer that the choice of media-types with hypermedia support as well as the adoption of standardized semantics (standard link relations, standard semantic descriptors and respect for HTTP protocol semantics) enables extensibility for web APIs and avoids unnecessary duplication of efforts.

After reading the book, I am convinced that standardization really pays off. The point made in the chapter about CoAP sums up the situation (although the chapter emphasizes on hypermedia): even in a chaotic environment such as the Internet of Things, appliances can coordinate if they share the same constraints on protocol and application semantics.

I am still in doubt about the compulsory usage of hypermedia. It is hard for me to conceive that all clients should adopt the strategy of navigating a web API by following links from a "home page" instead of going straight to the point (e.g. by constructing URLs). Apparently the "API call" metaphor, combined with machine-readable profiles (such as JSON-LD + Hydra) could provide the same benefits: clients would be able to detect and respond to changes immediately (as much as hypermedia-oriented clients) provided that changes were additive or backwards-compatible (otherwise hypermedia-oriented clients would also break).

On a side note, I think the reader would benefit from a more organized book. I assume many readers missed several major points that were made only on Appendix C, points that would fit nicely on a conclusion chapter. Instead, the body of the book ends in an apparently optional chapter about CoAP. Rather anticlimactic.

[Brian · Rating 4 out of 5]

(4.0) I learned from this things I shouldn't've needed to learn from this

Distilling to a single point: don't just do REST; adopt existing standards, naming conventions and machine readable methods of imbuing your API responses with meaning, full hypermedia. They point to lots of places to find existing standards to piggy-back on, including their own (e.g. ALPS).

It also goes into a fair amount of detail in protocols of little interest to me but introduces a good methodology for designing truly RESTful APIs--and why this is a good goal.

Still struggle with how clients can truly adapt to changes in semantic representation though. Going after machine readable indications of what fields mean doesn't lead to automatically changing behavior when new fields added or changed.

Very sold on importance of hypermedia in open web APIs though (whereas I kind of understood before but thought orthodox REST sounded a little overly academic).

[Federico · Rating 2 out of 5]

A good historical introduction to how people used to think about REST in the time when the semantic web was all the rage. One of the assumptions is that applications are mostly about exchanging information. If you're not interested in microformats and this sort of thing, probably you need to look elsewhere for help with your REST.

[Matthew · Rating 4 out of 5]

From page 237:

Think of the World Wide Web (and of any other RESTful API) as a technology stack. URLs are on the bottom; they identify resources. The HTTP protocol sits on top of those resources, providing read access to their representations and write access to the underlying resource state. Hypermedia sits on top of HTTP, describing the protocol semantics of one particular website or API.

The bottom layer answers the question “Where is the resource?” The middle layer an‐ swers the question “How do I communicate with the resource?” The top layer answers the question “What next?”

So far, this book has focused on the top layer of the stack—“What next?” That’s because the top layer is the tricky one. Most of today’s APIs use URLs and HTTP correctly, but don’t even bother with hypermedia.

That excerpt summarizes the book in my mind—the book focuses on hypermedia even though most APIs "don't even both with [it]." Many good principles are described, but you'll have to decide for yourself how pragmatic the content is.

[Dzmitry Kishylau · Rating 2 out of 5]

The book is not entirely useless - there are several interesting and non-trivial observations about semantics of HTTP protocol, and really nice reference about HTTP status codes (in appendix). However, the truth is that there's simply not much authors (or anyone else) can say on the subject - clearly not enough for 300+ page book. So they water down, and water down again, and the result is rather disappointing read.

[Chris Sullins · Rating 4 out of 5]

Solid book. The most important parts seem to be the API design procedure (Chapter 9), and Appendix C, a discussion of Roy Fielding's PhD dissertation that identified the concept of Representation State Transfer (REST).

[Jahongir Rahmonov · Rating 3 out of 5]

Not necessarily something that I would expect from a book with this title. Got bored.

[Jeffrey · Rating 2 out of 5]

Started out strong, but falls apart and becomes impractical.

[Alb85 · Rating 2 out of 5]

Libro che risulta noioso. Gli esempi pratici di servizio REST presenti nel testo sono solo due: un troppo semplice blog e un troppo complesso gioco per uscire da un labirinto. Nel libro non viene spiegato come testare il codice presentato. C’è troppa teoria scritta in modo poco accattivante.

Nozioni base apprese
- REST non è un protocollo, è un insieme di vincoli di design.
- URL identifica una ed una sola risorsa. Quando il client fa una richiesta HTTP GET, riceve una rappresentazione di quella risorsa. Il client non vede direttamente la risorsa. GET è un metodo "safe".
- Una risorsa è qualsiasi cosa può venire espressa in bit.
- Una rappresentazione della risorsa è un qualsiasi documento leggibile da una macchina che contiene info sulla risorsa. Ci possono essere più rappresentazioni per la stessa risorsa. Anche una POST contiene la rappresentazione di una risorsa, in questo caso l'utente vorrebbe che venisse creata (o modificata).
- Il termine “statelessness” significa che al server non importa sapere lo stato del client.

Livelli di compatibilità tra Web-API:
- URL
- Protocollo HTTP (con 8 tipi di messaggi: GET, DELETE, POST, PUT, HEAD, OPTIONS, CONNECT, TRACE). In RFC 5789 che anche il messaggio PATCH. Poi c'è l'estensione di HTTP con i messaggi LINK e UNLINK.
- Nel caso di documenti HTML si possono usare solo GET e POST. Ipermedia definisce i controlli di HTML. Ad esempio: < a > è una GET triggerata dall'utente, < img > è una GET triggerata automaticamente, < form > può essere una GET o POST triggerata dall'utente. L’Ipermedia è un modo per il server di dire al client quali richieste HTTP il client potrebbe voler fare in futuro.
- JSON
- Collection+JSON: è un modo di esprimere liste che descrivono the risorse http.

[Leonardo]

If you’re looking to build APIs instead of just using them, or if you want to learn more about the theory of their construction and syntax, I recommend RESTful Web APIs by Leonard Richardson, Mike Amundsen, and Sam Ruby (O’Reilly). This book provides a strong overview of the theory and practice of using APIs on the web.

Web Scraping with Python Pág.190

[Hesham Amin · Rating 3 out of 5]

The book takes the reader to the next step to designing REST APIs after following HTTP semantics. It shows how difficult it is to bridge the semantic gap in web APIs. However following even a subset of the guidelines mentioned in this book will make you're API easier to consume, although not as easy to change as you'd hope.
I believe appendix C (An API Designer's guide to the Fielding Dissertation) should have come earlier in the book.

[Amit · Rating 4 out of 5]

Good review of http protocol

[OrangeTime · Rating 5 out of 5]

Complete guide to design RESTful Web APIs

[Cody Ray · Rating 5 out of 5]

This was an awesome book, and a great summary of what I had spent the past couple of weeks reading (which was a smattering of specifications) trying to figure out how it all fits together. He laid out some good models (fiat standards, personal standards, corporate standards, open standards) as well as . The best bit was how it talked about the semantic gap and how "profiles" like AMPS fit into everything.

~I think the huge missing gap (in this book and/or in my knowledge) is how to actually program clients to make sense of this, and how that ties my hands as an API provider still. (For example, we've shifted the problem from versioning our API to versioning our profiles, IIUC)~

EDIT: The author Mike Amundsen published a follow-up book called RESTful Web Clients which addressed the "huge missing gap" described above. So I'm revising this one to 5 stars. :D Here's my review of RESTful Web Clients - https://www.goodreads.com/review/show...

[Jascha · Rating 4 out of 5]

Everyone has certainly heard the term RESTful, and possibly used it many times, but probably very few people know what it is and how a good, usable RESTful API should be written. Having definitely won its war with SOAP—well, they are used in different contexts, the popularity of RESTful APIs exponentially increased throughout the latest years. RESTful Web APIs makes it easy for everyone to understand the pros and cons of this technology and teacher the reader the importance of standards, and how to write an API following them.

Released back in 2013, it is the second time I get through this book, which is somethign rare I reserve for special books. I have enjoyed it even more than two years ago. Why? Because this book is about writing good, reusable code. It's about following the standards and, mostly, getting aware of those that exist before we write our own.

The author starts with an in-depth analysis of REST and SOAP. Not only they good and cons, but how they differ and in which scenario ons is preferred to the other. The concept of standard, as well as that of fiat standard, is also discussed. Through these first chapters, the author focuses on the costs and benefits a developers gets by siding with the standards that are already available. Among them, for example, collection+json, over a pure fiat json.

Talking about standards, a lot of space is given to HTTP. The author covers it brilliantly but still, in an easy to follow way. The reader doesn't really get lost as there are no abrupt changes of subject between the paragraphs. Each and every verb of the standard is covered, including those that were introduced through extensions—with examples, of course! Other standards covered are HAL+XLM and Atom, just to mention a couple.

The discussion ineviatably gets to the point (chapter 9) we probably bought this book for: which (HTTP) methods should our API implement? Which standard(s) should we follow? The author presents his ideas through interesting and well explained examples.

Another concept that is crucial to this book is that of hypermedia. The author, fro the very beginning up to the end, describes it and its importance.

Overall is a great read for any developer, not only those interested in APIs. It's a title about writing reusable code, following the standards, which is something that maybe does not pay off in the short term, but that does in the mid/long term. The examples are well explained and easy to follow. So are all the concepts presented.

As usual, you can find more reviews on my personal blog: books.lostinmalloc.com. Feel free to pass by and share your thoughts!

[Keith Christoffers · Rating 3 out of 5]

New

[Richard Magahiz · Rating 4 out of 5]

This book positions itself to be the basic reference for developers who are designing distributed computing systems that use the dominant pattern of REST (Representational State Transfer). The authors describe how most API standardization still centers around human readable documentation of fiat standards instead of machine readable formats which have been around for some time now, and the benefits of moving to a more machine-centered approach. The problem of upgrading an API can be solved at the design stage by the right choice of hypermedia and the use of existing standards when possible. They take the approach of devoting the first half to elementary examples of resource representations, in html, json, xml, or forms derived from these standards, without listing specific examples of code to generate or consume those representations. The latter half describes some standards which did not exist or were not widespread at the time of the previous version of the book, and while it does not try to be an encyclopedic list of APIs, it does point to online repositories where new standards will be published.
It was a good reference book for someone who isn’t currently an expert in the area covered, with down to earth (if not to say simplistic) examples to illustrate the best practices they discuss.

[Jonathan · Rating 5 out of 5]

This book serves as a sort of sequel to the O'Reilly classic "RESTful Web Services" published back in 2007 (by Richardson and Ruby). Most conventional web APIs today do not fully embrace hypermedia - a key feature of the web that has made it so attractive to humans when organizing information online. Instead, most APIs today embrace most of the REST principles (data organized as resources, uniform interface, addressability, safety, idempotence, etc.) but rely on out-of-band documentation (for human consumption) to facilitate discovery and actual usage. This book is a convincing and practical manifesto on how hypermedia can be embraced in our machine level interfaces.

Even though RESTful principles have been well articulated by Fielding and others over a decade ago, this notion of hypermedia APIs is still a bit cutting edge for most developers. Given the lack of well-accepted standards and conventions in representations, etc., much of the book presents examples utilizing an assortment of formats, some of which the authors' have come up with themselves. The book therefore better thought of as a conceptual presentation of hypermedia APIs, what they might look like and how implementation of such APIs might be approached. A very informative read for any developer who implements or consumes web API, and highly recommended.

[Laurent · Rating 5 out of 5]

This book should be mandatory reading for all developers that build or simply use Web APIs.
It aims to help API designers build better, future-proof systems, using hypermedia. This is not a simple task, so it doesn't have all the answers. REST might have won the philosophical debate against SOAP and others like it, but there is still a lot to do to have real RESTful APIs. The book points out very well the shortcomings of current design practices and explains why leaning towards a more hypermedia-based approach will help.

[Jose · Rating 4 out of 5]

I made myself get through this book because I want to know about this subject. I don't hear the term Hypermedia a lot at my job even though we do web services, and I have heard the term "RESTful" and "idempotent" a couple of times. I have a feeling many people use the term REST without really knowing what that term means. Or, just understanding one aspect of REST. This book goes into great detail about the philosophy of REST services, but does not prescribe any technology to implement it. This book was very useful to me, but only because I am working on web services now.

[Francois D’Agostini · Rating 2 out of 5]

The way the book is written and the examples it provides was way too abstract for me.
Besides, it really seems that hypermedia APIs are not so much used in the real world. That is why most of the examples of the book are really hypothetical and cannot be applied on the current apis available on the Web.

The problem is that outside of what Hypermedia is about, I have the feeling I did not learn much more thant that, even though the book is quite big.

Anyway, maybe I am not yet ready to digest such a book :)

[Seth · Rating 2 out of 5]

Definitely some interesting ideas that are well explained but I felt that a key purpose of the book was to promote the author's collection structure as a "standard". I'm not sure that this collection really simplifies usage as much as he proclaims because an API consumer still needs semantic knowledge to process results. However, having a standard approach for a specific API is definitely a good thing.

[Sulava Singha · Rating 3 out of 5]

This book is good for those who are designing new RESTful web APIs and want to get an overview of what it takes to design usable APIs. A great overview on hypermedia , semantic challenges and what it takes to design your own templates. Examples are mostly based on collection+json. This book provides you a meaningful subject knowledge on creating secure application, creating for search or pagination.

[Steven Cummings · Rating 4 out of 5]

This is pretty much the book for the current state of web service design. It clarifies why the principles matter and answers the questions you may have not even thought to ask based on the authors' deep experience with the web platform.

This isn't the best day to day guide, but it is the best rundown of the star of the art.

[Kirill · Rating 5 out of 5]

I liked many thought-provoking design examples in different hypermedia and non-hypermedia formats. Authors emphasize contrasts between generic and domain-specific formats and show possible ways on how to choose what you need. The "Seven-Step Design Procedure" is a particularly good exercise.

[Sumit · Rating 4 out of 5]

An excellent conceptual guide to RESTful APIs. Explains REST in details and also discusses the various REST standards such as JSON, XML and AtomPub in detail. The examples however could be more practical.

[Marco Pavan · Rating 5 out of 5]

If more API designer had read this book, the world of IT integration would be a much better and easier place where to live.

[Tobias Macey · Rating 5 out of 5]

This is an excellent view of how to structure web APIs so that they are flexible, maintainable and usable. A definite must-read for anyone who works with the web.

[Shelling · Rating 4 out of 5]

Much better than the cookbook, a must read for Web API development.

[Einar · Rating 5 out of 5]

Very useful.