Chapter 8: Building APIs

Design and Build Great Web APIs — by Mike Amundsen

Defining the API Build process

For the purpose of this chapter, the “build process” is the work of translating our design work into source code that actually does the work we set out to do.

Sometimes build is reserved for that portion of coding that starts with checking in written code and involves things like compiling, testing and deploying the code on a server somewhere. That will be covered in following chapters (The Release Phase).

Relying on a Repeatable Process

When we build a lots of APIs its valuable to have a consistent, repeatable process. The main benefit of a repeatable process is that its something you can show and teach others. A good process is also easily monitored.

Here I will describe a short-walkthrough of the build process used by the author called DARRT. DARRT is a process for building code from design documents. The DARRT framework was created as a teaching tool and as a quick way to start lightweight micro-service and API projects. This framework is not recommend for production use, you can take the lessons you learn here and apply them to whatever framework or programming language you and your team are using.

DARRT stands for data, actions, resources, representations and transitions.

Data

The data.js file holds all the information about the properties (or “state”) the service needs to deal with. In many API implementations, this is handled by a database. But APIs dont really understand data storage; they just understand passing properties back and forth.

The data.js file includes four small sections:

• Properties — a list of state values this API needs to keep track of throughout the lifetime of the service
• Requireds — required elements when writing a record
• Enums — properties having a limited set of valid values
• Defaults —default values of properties to create a valid record

Actions

The action.js file contains all the actions we defined in our API design. These are internal functions in our service, not the external endpoints of the API. Each action is represented by a single function.

These two data and action files represent the internal elements of our API service. Let’s now ficus on the external elements: the exposed resources, the response formats and the request transitions.

Resources

We use the resources.js file to implement all the externally addressable API endpoints for the service. It references the key elements of the external endpoints of our HTTP API along with the methods that are supported by each resource.

Each of the functions listed in the file gets called when the associated URL and HTTP method are used by the client app. The role of each function is to 1) accept the request parameters, 2) process those parameters and 3) formulate an HTTP response and return it to the caller.

The three DARRT elements described above — data, actions, resources — represent the complete “loop” of requesting a resource and executing an associated action. The next two DARRT elements pertain to the details of how responses will be formulated — how to populate the response and which format to use when returning that response.

Representation

This refers to the format of the HTTP API responses. HTTP APIs can use a wide variety of formats to represent HTTP responses. The most common response for APIs today is plain JSON (application/json), but a number of other formats exist as well. You can vary the response representations by simply loading one of the preset formats and referencing them when implementing the API.

The representation.js file controls which formats are available for API responses.

Transitions

The transitions.js defines which operations are available for each resource representation. It holds a set of declarations for forms and links related to the API.

An example of a link transition in HTML is the anchor tag and an example of a form transition in HTML is the

This chapter wraps up the build phase of the book (sketch, prototype and build). Next we move into the release phase where we will cover testing, securing and deploying the working API.