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