O'Reilly logo

RESTful Web APIs by Leonard Richardson, Sam Ruby, Mike Amundsen

Stay ahead with the world's most comprehensive technology and business learning platform.

With Safari, you learn the way you learn best. Get unlimited access to videos, live online training, learning paths, books, tutorials, and more.

Start Free Trial

No credit card required

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. ...

With Safari, you learn the way you learn best. Get unlimited access to videos, live online training, learning paths, books, interactive tutorials, and more.

Start Free Trial

No credit card required