Book Review: RESTful Web APIs by Leonard Richardson and Mike Amundsen
For the past few months, much of my time has been absorbed by my senior design project at UAH. Setting aside the specifics of what my group and I are working on, the design calls for a web service that has an open API to allow for the simple creation of new clients. Looking at the options, it was quickly obvious that we wanted to approach the API design with a RESTful architecture rather than using SOAP, owing to its flexibility and the comparative ease with which a new client can be implemented to use a new RESTful API. Unfortunately, though using RESTful simplified some aspects of the project, knowing that the approach desired didn’t help me design the API for the project, so I turned to O’Reilly for a book to help guide me along the process. As luck would have it, O’Reilly shortly had a sale on RESTful books, and I picked up RESTful Web APIs.
RESTful Web APIs starts at the beginning, with an examination of the web itself, looking at how hypermedia works, and how, starting from just the home page of a website, a client can quickly build up a picture of the services offered by the server. Starting in Chapter 1, it sets up the notion of the semantic challenge - how to get a computer to understand what it is looking at rather than forcing a human to understand and make decisions. Though this seems like a topic to be contained in a book on artificial intelligence rather than API design, pursuing a smaller semantic gap can drastically improve the usability of your API from a client programmer’s perspective.
With that introduction, the next chapters continue to focus on HTTP, describing and defining the different methods available, like GET, DELETE or PUT, and relating them to how they should be used in the context of CRUD (create, read, update, delete) operations. Soon after, the notion of hypermedia is examined in detail, as well as how it is used. Hypermedia is pursued again later on, with the book listing many different types of hypermedia media types to demonstrate how hypermedia should be used, and in contrast instances were it could have been used to produce a better product. Having looked at different media types, the notion of a profile – basically documentation which the client software can look at to decide how to treat data – is examined and mechanisms for writing good profiles are listed.
Then, in Chapter 9, an approach to designing RESTful APIs is defined in seven steps, going from what resources are provided, drawing a state diagram, making names consistent, selecting a media type and choosing a media profile to the actual implementation and publication of the API. Fortunately this section includes enough examples that it proves a fairly good way to first get a grasp of RESTful design and then later to refer to when making the design. In fact, I’ve found I’ve referred to this chapter more than once already, and expect to refer to later steps over the next few weeks as we complete more of the project.
Having gone through the stages of designing a RESTful API in Chapter 9, the book turns to providing you with information about what resources are already available for you to take advantage of, such as a variety of hypermedia types and HTTP information that is helpful to know when making an API, things like Conditional GETs and Look-Before-You-Leap Requests. Several chapters are devoted to this type of information, in addition to a handy set of appendices which list the HTTP status codes and headers, as well as including an “API Designer’s Guide to the Fielding Dissertation” (Roy Fielding being the author of the dissertation originally defining REST).
Though only a single chapter is devoted solely to the actual design of RESTful APIs, don’t get the impression that this book is mostly a waste of space. Unless you are already intimately familiar with HTTPs various methods (and how they should be used), hypermedia types, using and writing profiles and a lot of general background knowledge useful for writing web service APIs, then this book could be of service to you.
Overall, I’d say a developer looking to learn more about RESTful APIs or gearing up to design or implement on would do well to read this book. Though at times I had to look back a page or two to be sure I understood the current page, and in some areas detailed examples were thin on the ground, overall the book did a good job at communicating the subject, and in the end led me to be able to define what I hope is a fairly good RESTful API.
Ebook Notes: As with most of the ebooks I’ve gotten from O’Reilly, I didn’t have any particular problems reading this on my Kindle.