A Seven‑Step Methodology for Designing Web APIs

Designing a Web API involves more than just URLs, HTTP status codes, headers, and payloads; the design process—essentially how the API is "observed and felt"—is crucial and worth the effort. This article briefly summarizes a methodology that exploits the strengths of both HTTP and the Web, and it works for other protocols such as WebSockets, XMPP, or MQTT, making future multi‑protocol support easier to implement and maintain.

API Design Seven‑Step Method

We will give a concise overview of the design methodology presented in Richardson and Amundsen’s book RESTful Web APIs . Because of space limits we cannot explore every step in depth, but the article can serve as a guide for creating a custom Web API design process suited to your organization’s skills and goals.

Note: the list appears to have seven steps, but only five are actual design steps; the remaining two (implementation and publishing) provide an end‑to‑end experience.

Step 1: List All Components

The first step is to enumerate every data fragment that a client might retrieve from or send to the service. These are called semantic descriptors: they describe the meaning of the data in the client’s context. For a simple to‑do list app the descriptors might be:

id – unique identifier for each record

title – the title of the to‑do item

dateDue – the due date for the item

complete – a yes/no flag indicating whether the item is finished

A full‑featured app would have many more descriptors (categories, user information, etc.), but we keep it simple to highlight the process.

Step 2: Draw a State Diagram

Next, draw a state diagram based on the proposed API. Each box represents a possible representation—a document containing one or more semantic descriptors identified in Step 1. Arrows show transitions triggered by protocol requests, indicating whether the transition is safe (e.g., HTTP GET) or unsafe/non‑idempotent (e.g., HTTP POST) or unsafe/idempotent (e.g., PUT).

For the to‑do service the client may need to list items, filter the list, read a single item, and mark an item as complete. The diagram also lists the corresponding actions (read‑list, filter‑list, read‑item, create‑item, mark‑complete).

Iterating between Steps 1 and 2 helps ensure that all client‑required actions and data points are captured.

Step 3: Reconcile "Magic Strings"

All descriptor names are essentially "magic strings"—they have no intrinsic meaning beyond the API contract. Reconcile them by adopting well‑known public vocabularies such as Schema.org, microformats.org, Dublin Core, and IANA Link Relation Values. This improves discoverability for developers.

For the to‑do example the reconciled names become:

id → Dublin Core identifier

title → Schema.org name

dueDate → Schema.org scheduledTime

complete → Schema.org status

read‑list → IANA collection

filter‑list → IANA search

read‑item → IANA item

create‑item → RFC 5988 http://mamund.com/rels/create-item

mark‑complete → IANA edit

Step 4: Choose a Media Type

Select a media type that can convey both data descriptors (e.g., "identifier", "status") and action descriptors (e.g., "search", "edit"). Popular hypermedia formats include HTML, HAL, Collection+JSON, Siren, JSON‑API, and UBER. The choice should also suit the target protocol (HTTP, WebSockets, XMPP, MQTT, CoAP).

In this example we use HTML as the message format with HTTP as the protocol, because HTML supports lists ( <ul>), items ( <li>), spans for data elements, and links/forms for actions.

Step 5: Create a Semantic Profile

A semantic profile is a document that lists all descriptors used in the design, providing guidance for developers without prescribing an implementation. Formats such as ALPS and JSON‑LD + Hydra are recommended.

Service Descriptor Formats

WSDL

AtomSvc

WADL

Blueprint

Swagger

RAML

Profile Formats

Application Level Profile Semantics (ALPS)

JSON‑LD + Hydra

Both are relatively new; ALPS is an IETF draft, while JSON‑LD became a W3C Recommendation in early 2014 and Hydra remains an active community draft.

Step 6: Write Code

Hand the design documents (state diagram and semantic profile) to the server‑ and client‑side developers. The HTTP server should implement the state diagram, using the media type chosen in Step 4, and include hypermedia controls that correspond to the actions described in the profile.

Step 7: Publish Your API

Publish at least one stable URL that always responds (the "board URL"). Also publish the profile document so new implementations can link to it. Providing human‑readable documentation, tutorials, and examples helps other developers adopt the service.

Conclusion

This article presented a set of steps for designing Web APIs, emphasizing correct description of data and actions in a machine‑readable way so that developers can implement client and server sides without directly touching the design.

List all components – gather every data element the client needs.

Draw a state diagram – record all actions (state changes) the service provides.

Reconcile magic strings – align public interface names with well‑known vocabularies.

Choose a media type – select a message format that best matches the target protocol.

Create a semantic profile – write a guide documenting all descriptors.

Write code – share the profile with developers and build implementations that conform to the diagram and profile.

Publish your API – expose a stable URL and the profile so others can build on it.

Early discovery of missing elements, iterative refinement, and thoughtful compromises lead to a robust, reusable API design that can evolve as new protocols or formats are required.

About the Author

Mike Amundsen is the Chief API Architect at Layer7 Technologies, helping people create excellent Web APIs. An internationally known author and speaker, he consults and lectures on distributed network architecture, Web application development, cloud computing, and related topics. He has authored more than a dozen books. (Source: InfoQ)