I have a new software project in mind. I want to do it right. So I’ll use a RESTful web API. Which, of course, like any good software developer, I already understood pretty well, but I wanted to just brush up on my REST game, and make sure I got all the best practices down. Thus began my search on Amazon for a good book about REST. I found one. I read it. And I realized then that my previous “pretty good understanding of REST” was almost completely incorrect. And yours probably is, too.

Outlined here is my suggested reading list to familiarize yourself with REST (jump straight to the reading guide). So far, I have two books I recommend–the two I’ve read. I think I got lucky and read two good books, and I happened to read them in approximately the right order.

My primary goal is to help you, as someone who has a “pretty good concept of REST” which turns out to be mostly wrong, get to the right answer, with the least amount of effort and confusion.

First, a quick test to see if you have a “pretty good concept of REST which is mostly wrong”, or if you really understand it.

1. Do you know when to use the HTTP DELETE verb?
2. Do you know what an Accepts: header does?
3. Is it RESTful to send an HTTP GET request to http://example.com/?item=123&action=delete to delete an item?
4. Do you know which link types are acceptable within a REST API?

The answers are:

1. When you want to delete a resource. If you’ve never used or heard of the HTTP DELETE verb, you should read the rest of this document.
2. It tells the server which content type(s) the client is prepared to accept. If you didn’t realize the client could specify this, or when they might want to, you should read the rest of this document
3. No. In a proper REST API, an item deletion should always use a DELETE verb (not GET), or occasionally, a POST. GETs must always be safe–that is, they should never modify server data. If this is new to you, you should read the rest of this document
4. The answer is, it depends. But you should have a good idea of how to determine the proper link types without reading human documentation for a given REST API. If this is new to you, read on.

If you have a solid understanding of these four questions and answers, then you probably are in the minority who have a good, proper understanding of REST, and following this reading guide probably won’t teach you much.

Now for the list of books:

1. REST in Practice: Hypermedia and Systems Architecture (or for Kindle)
2. RESTful WebAPIs (or for Kindle)

But not so fast! These books overlap a bit, and they have different strengths and weaknesses. So let me offer my advice on the order in which to read these books.

REST in Practice is an excellent primer to REST. It does an excellent job of explaining the four levels of a REST service (Levels 0 through 3). Quoting from the preface of the book itself:

Like most of us, you're probably already building something that feeds into the Web, and you've probably used tools and patterns for the Web that seem pretty useful. Then you've tackled typical enterprise problems and wondered why it can't be as nice as the web stuff.

…

You may even be an enthusiast who has heard about REST and wants to know what it is all about. You want to learn about “hypermedia” and the REST architectural style so that you can build resource-oriented systems and implement sophisticated business protocols atop the Web.

This book will help.

And I agree completely. This book will help, by laying the conceptual foundations upon which REST rests. Where this book lacks is in the final chapters, in the discussion of hypermedia. I believe there are two primary reasons for this shortcoming. First, it’s just a plain confusing domain of information. And second, the book is nearly a century old (in Internet years– it was published in 2010), and the world of hypermedia has made many important advancements since then.

The book is fun to read. It follows the whimsical, but applicable, development of a coffee-ordering REST API for the fictional “Restbucks” Coffee chain, as it grows from employing a single barista, to becoming a chain with multiple locations and nation-wide loyalty programs and specials. This back story provides the necessary context for the REST concepts to fall neatly into place.

Aside from being dated, the book’s other weakness, in my opinion, is spending too much time on the specifics of client and server implementations details in Java and .NET. Don’t feel guilty for skipping these sections. Unless you’ve never written client or server code before, you probably won’t glean much of value from these sections. Skip them with impunity, if you wish.

I suggest you begin your reading with REST in Practice, and read chapters 1 through 4, and chapter 6 thoroughly. Chapter 5 ought to be at least skimmed. Beyond chapter 6, some good concepts are introduced, but they get muddled, and largely buried beneath the details of XML-rich document formats. At this point, it would be good to familiarize yourself with some of the concepts, by skimming chapters 9, and 10. Chapters 7, 8, and 11 cover mostly obsolete concepts. You should only need to read them if you’ll be using these specific formats. Read or skim chapter 12.

At this point, you should have a pretty good understanding of what a REST API is, and how to write one, except for one missing, and very vital piece. You’ll understand conceptually what Hypermedia is, and where it fits into the REST puzzle, but you won’t know how to use it. This is where my second reading recommendation comes in.

RESTful Web APIs is the new edition of the popular, but now out-of-print RESTful Web Services by the same author. The new edition focuses heavily on Hypermedia in the context of REST, and really picks up where you left off if you followed my advice above. It's also 3 years newer than REST in Practice, which is a long time in an area of new technology, such as REST and Hypermedia. The 3 years make a huge difference! Where REST in Practice, for instance, recommended Atom, RESTful Web APIs points out that by the time of its publishing, Atom was all but obsolete, and provides several alternatives which will likely serve you better.

Chapters 1-2 will be review for you, if you’ve read REST in Practice. I suggest skimming them, though, just to give you some context, as the rest of the book refers back frequently to examples presented in these initial chapters. Chapter 3, while technically, also offers a fresh perspective on resources and representations, upon which the rest of the book builds. So I suggest reading it thoroughly.

Chapters 4-9 are the meat of the book, with the culmination in chapter 9, with a specific 7-step suggestion for designing your own API from the ground up. Those 7 steps, if not all of chapter 9, probably belong on a poster on your office wall, if you’ll be writing more than one API in your career.

Chapter 10 is more for reference, and provides a summary of readily-available Hypermedia formats for your perusal so you can pick-and-choose the bits to plug into your new API. You will probably want to just skim it, and read the sections that apply specifically to your problem domain.

Chapter 11 is essentially a whirl-wind repetition of REST in Practice’s chapters 3 and 6. Skim it if you wish.

Chapter 12 covers RDF, and should be read thoroughly, if only to understand how RDF fits (and doesn’t) fit into REST.

Here’s my reading guide:

• Read REST in Practice, Chapter 1: The Web as a Platform for Building Distributed Systems
• Read RESTful Web APIs, Chapter 3: Resources and Representations

  RESTful Web APIs offers a newer, arguably healthier view of resources and representations. If you have both books at hand, I suggest reading this chapter immediately after chapter 1 of REST in Practice, just so you have both paradigms in mind. It will help you to be mindful of the differences as you read the rest of the material.

• Read REST in Practice, Chapter 2: Introduction to Restbucks: How to GET a Coffee, Web Style
• Read REST in Practice, Chapter 3: Basic Web Integration
• Read REST in Practice, Chapter 4: CRUD Web Services
• Read or skim REST in Practice, Chapter 5: Hypermedia Services

  I suggest reading this, for continuity, although it will be largely redundant with much of RESTful Web APIs, starting with chapter 4. If you're in a hurry, you can skip this, though.

• Read REST in Practice, Chapter 6: Scaling Out
• Skim REST in Practice, Chapter 9: Web Security
• Skim REST in Practice, Chapter 10: Semantics
• Read or skim REST in Practice, Chapter 12: Building the Case for the Web
• Skim RESTful Web APIs, Chapter 1: Surfing the Web
• Skim RESTful Web APIs, Chapter 2: A Simple API
• Read RESTful Web APIs, Chapter 3: Resources and Representations

  Only if you didn't read this earlier. Or you may wish to re-read or skim through it to refresh yourself on the material.

• Read RESTful Web APIs, Chapter 4: Hypermedia

  Much of the material in this and the following chapter was already touched upon in chapter 5 of REST in Practice, but it is given more attention here.

• Read RESTful Web APIs, Chapter 5: Domain-Specific Designs
• Read RESTful Web APIs, Chapter 6: The Collection Pattern
• Read RESTful Web APIs, Chapter 7: Pure-Hypermedia Design
• Read RESTful Web APIs, Chapter 8: Profiles
• Read RESTful Web APIs, Chapter 9: The Design Procedure

  This chapter is the gold mine. This is where all the pieces you've been learning finally fall into place in a REST API of your own design!

• Skim RESTful Web APIs, Chapter 10: The Hypermedia Zoo

  This is a summary of numerous existing Hypermedia formats (including Atom and AtomPub, covered in chapters 7 & 8 of REST in Practice). You'll want to skim this, for an overview of available formats. But be aware that this book is already 2 years old, and there are new formats all the time. This won't be the end of your search for existing formats!

• Skim RESTful Web APIs, Chapter 11: HTTP for APIs

  REST in Practice covers these topics in greater detail in chapters 4 and 6.

• Read RESTful Web APIs, Chapter 12: Resource Description and Linked Data

  Any forum post on REST these days talks about RDF, linked data, and a dozen other related buzzwords. This chapter helps explain what those are, and how they do (and don't!) relate to REST.

That’s my suggested reading.

Please offer your feedback and questions below in comments. If you have any additional resources I should add to the list, please let me know!