Seven-Steps for Designing a web API

2 בינואר 2014

no comments

This is the procedure described by Leonard Richardson in his book : RESTful Web APIs .

The procedure consist of seven steps. Doing some preparatory work
up front will help you choose a representation format and keep your profile as simple
as possible.

1. List all the pieces of information a client might want to get out of your API or put
into your API. These will become your semantic descriptors.
Semantic descriptors tend to form hierarchies. A descriptor that refers to a realworld
object like a person will usually contain a number of more detailed, more
abstract descriptors like givenName. Group your descriptors together in ways that
make intuitive sense.

2. Draw a state diagram for your API. Each box on the diagram represents one kind
of representation—a document that groups together some of your semantic descriptors.
Use arrows to connect representations in ways you think your clients will
find natural. The arrows are your state transitions, triggered by HTTP requests.
You don’t need to assign specific HTTP methods to your state transitions yet, but
you should keep track of whether each state transition is safe, unsafe but idempotent,
or unsafe and non-idempotent.
At this point, you may discover that something you put down as a semantic descriptor
(the customer of a business) makes more sense as a link relation
(a business links to a person or another business using the link relation customer). Iterate
steps 1 and 2 until you’re satisfied with your semantic descriptors and link relations.
Now you understand your API’s protocol semantics (which HTTP requests a client will
be making) and its application semantics (which bits of data will be sent back and forth).
You’ve come up with a list of magic strings (semantic descriptors and link relations)
that make your API unique, and you know roughly how those magic strings will be
incorporated into HTTP requests and responses. You can then move on to the following

3. Try to reconcile your magic strings with strings from existing profiles.
Think about IANA-registered link relations, semantic descriptors from or,
names from domainspecific media types, and so on.
This may change your protocol semantics! In particular, unsafe link relations may
switch back and forth between being idempotent and not being idempotent.
Iterate steps 1 through 3 until you’re satisfied with your names and with the layout
of your state diagram.

4. You’re now ready to choose a media type (or define a new one). The media type
must be compatible with your protocol semantics and your application semantics.
If you’re lucky, you may find a domain-specific media type that already covers some
of your application semantics. If you define your own media type, you can make it
do exactly what you need.
If you choose a domain-specific media type, you may need to go back to step 3, and
reconcile your names for semantic descriptors and link relations with the names
defined by that media type.

5. Write a profile that documents your application semantics. The profile should explain
all of your magic strings, other than IANA-registered link relations and strings
explained by the media type.
I recommend you write the profile as an ALPS document, but a JSON-LD context
or a normal web page will also work. The more semantics you borrowed from other
people in step 4, the less work you’ll have to do here.
If you defined your own media type, you may be able to skip this step, depending
on how much of this information you put in the media type specification.

6. Now it’s time to write some code. Develop an HTTP server that implements the
state diagram from step 3. A client that sends a certain HTTP request should trigger
the appropriate state transition and get a certain representation in response.
Each representation will use the media type you chose in step 4, and link to the
profile you defined in step 5. Its data payload will convey values for the semantic
descriptors you defined in step 1. It will include hypermedia controls to show the
client how to trigger the further state transitions you defined in state 2.

7. Publish your billboard URL. If you’ve done the first five steps correctly, this is the
only information your users will need to know to get started with your API. You
can write alternate human-readable profiles (API documentation), tutorials, and
example clients to help your users get started, but that’s not part of the design.

Hope this helps


Add comment
facebook linkedin twitter email

Leave a Reply

Your email address will not be published.

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>