RESTful Web APIs by Leonard Richardson and Mike Amundsen with a Foreword by Sam Ruby
- 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 real- world 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.
- 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 steps:
- Try to reconcile your magic strings with strings from existing profiles. I list some places to look in “The Semantic Zoo” on page 230. Think about IANA-registered link relations, semantic descriptors from schema.org or alps.io, names from domain- specific 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.
- 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.
- Write a profile that documents your application semantics. The profile should ex‐ plain 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.
- 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.
- 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.