Chapter 9. The Design Procedure

It’s taken quite a while, but I’m now in a position to address the basic concern that may have led you to buy this book. You need to design an API: what should it look like? In this chapter, I’ll lay out a procedure that begins with business requirements and ends with some software and some human-readable documentation.

Two-Step Design Procedure

In its simplest form, the procedure has two steps:

  1. Choose a media type to use in your representations. This puts constraints on your protocol semantics (the behavior of your API under the HTTP protocol) and your application semantics (the real-world things your representations can refer to).
  2. Write a profile that covers everything else.

This won’t necessarily give you a good API. In fact, this version of the procedure describes every API ever designed. If you wanted a really generic design that’s hard to learn, you’d blaze through step 1 by choosing application/json as your representation format. Since JSON puts no constraints on your protocol or application semantics, you’d spend most of your time in step 2, defining a fiat standard and describing it with human-readable API documentation.

That’s what most APIs do today, and that’s what I’m trying to stop. A big chunk of the work that goes into creating a fiat standard is unnecessary, and client code based on a fiat standard can’t be reused. But doing anything else requires some preparatory thought and a willingness to reuse other people’s work when possible. ...

Get RESTful Web APIs now with O’Reilly online learning.

O’Reilly members experience live online training, plus books, videos, and digital content from 200+ publishers.