Manu Cohen-Yashar's Blog

2 בינואר 2014

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

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

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

2. Draw a state diagram for your API. Each box on the diagram represents one kindof representation—a document that groups together some of your semantic descriptors.Use arrows to connect representations in ways you think your clients willfind 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, butyou 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). Iteratesteps 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 willbe 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 beincorporated into HTTP requests and responses. You can then move on to the followingsteps:

3. Try to reconcile your magic strings with strings from existing profiles. Think about IANA-registered link relations, semantic descriptors from schema.org or alps.io, names from domainspecific media types, and so on.This may change your protocol semantics! In particular, unsafe link relations mayswitch 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 layoutof your state diagram.

4. You’re now ready to choose a media type (or define a new one). The media typemust 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 someof your application semantics. If you define your own media type, you can make itdo exactly what you need.If you choose a domain-specific media type, you may need to go back to step 3, andreconcile your names for semantic descriptors and link relations with the namesdefined by that media type.

5. Write a profile that documents your application semantics. The profile should explainall of your magic strings, other than IANA-registered link relations and stringsexplained by the media type.I recommend you write the profile as an ALPS document, but a JSON-LD contextor a normal web page will also work. The more semantics you borrowed from otherpeople 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, dependingon 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 thestate diagram from step 3. A client that sends a certain HTTP request should triggerthe 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 theprofile you defined in step 5. Its data payload will convey values for the semanticdescriptors you defined in step 1. It will include hypermedia controls to show theclient 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 theonly information your users will need to know to get started with your API. Youcan write alternate human-readable profiles (API documentation), tutorials, andexample clients to help your users get started, but that’s not part of the design.