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.
In its simplest form, the procedure has two steps:
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. ...