The first four chapters introduce the concepts behind REST, as it applies to web APIs.
- Chapter 1, Surfing the Web
- This chapter explains basic terminology using a RESTful system you're already familiar with: a website.
- Chapter 2, A Simple API
- This chapter translates the lessons of the Web to a programmable API with identical functionality to the website discussed in Chapter 1.
- Chapter 3, Resources and Representations
- Resources are the fundamental concept underlying HTTP, and representations are the fundamental concept underlying REST. This chapter explains how they're related.
- Chapter 4, Hypermedia
- Hypermedia is the missing ingredient that ties representations together into a coherent API. This chapter shows what hypermedia is capable of, mostly using a hypermedia data format you're already familiar with: HTML.
The next four chapters describe different strategies for designing a hypermedia API:
- Chapter 5, Domain-Specific Designs
- The obvious strategy is to design a completely new standard that deals with your exact problem. I use the Maze+XML standard as an example.
- Chapter 6, The Collection Pattern
- One pattern in particular - the collection pattern - shows up over and over again in API design. In this chapter, I show off two different standards that capture this pattern: Collection+JSON and AtomPub.
- Chapter 7, Pure-Hypermedia Designs
- When the collection pattern doesn't fit your requirements, you can convey any representation you want using a general-purpose hypermedia format. This chapter shows how it works using three general hypermedia formats (HTML, HAL, and Siren) as examples. This chapter also introduces HTML microformats and microdata, which lead in to the next chapter.
- Chapter 8, Profiles
- A profile fills in the gaps between a data format (which can be used by many different APIs) and a specific API implementation. The profile format I recommend is ALPS, but I also cover XMDP and JSON-LD.
In this chapter, my advice begins to outstrip the state of the art at the time this book was written. I had to develop the ALPS format for this book, because nothing else would do the job. If you're already familiar with hypermedia-based designs, you might be able to skip up to Chapter 8, but I don't think you should skip past it.
Chapters 9 through 13 cover practical topics like choosing the right hypermedia format and getting the most out of the HTTP protocol.
- Chapter 9, The Design Procedure
- This chapter brings together everything discussed in the book so far, and gives a step-by-step guide to designing a RESTful API.
- Chapter 10, The Hypermedia Zoo
- In an attempt to show what hypermedia is capable of, this chapter discusses about 20 standardized hypermedia data formats, most of them not covered elsewhere in the book.
- Chapter 11, HTTP for APIs
- This chapter gives some best practices for the use of HTTP in API implementations. I also discuss some extensions to HTTP, including the forthcoming HTTP 2.0 protocol.
- Chapter 12, Resource Description and Linked Data
- Linked Data is the Semantic Web community's approach to REST. JSON-LD is arguably the most important Linked Data standard. It's covered briefly in Chapter 8, and I revisit it here. This chapter also covers the RDF data model, and some RDF-based hypermedia formats that I didn't get to in Chapter 10.
- Chapter 13, CoAP: REST for Embedded Systems
- This chapter closes out the core body of the book by covering CoAP, a RESTful protocol that doesn't use HTTP at all.
The back matter contains some handy references, a discussion of Roy Fielding's disseration, and the Glossary of terms.
- Appendix A, The Status Codex
- An extension of Chapter 11, this appendix provides an in-depth look at the 41 standard status codes defined in the HTTP specification, as well as a few useful codes defined as extensions.
- Appendix B, The Header Codex
- Similar to Appendix A, this appendix is also an extension of Chapter 11. It provides a detailed outline of the 46 request and response headers defined in the HTTP specification, as well as a few extensions.
- Appendix C, An API Designer's Guide to the Fielding Dissertation
- This appendix includes an in-depth discussion of the foundational document of REST, in terms of what it means for API design.
- Glossary
- The glossary contains definitions to terms you'll frequently encounter when working with RESTful web APIs. It's a good place to turn for familiarizing yourself with basic concepts or if you need a quick, at-a-glance reminder of a particular concept's definition.
