Using Templates for Documentation Driven API Design

This post was originally published on the Nordic APIs blog as “Using Templates for Documentation Driven API Design”. As an API provider it’s important to consider how consumers interact with your API. While most people leave this task to the very end, API design should, in fact, begin with clear and concise documentation. This practice is often called “Documentation Driven Design” or “Documentation Driven Development” and is followed by many practitioners around the world. Tom Preston-Werner, founder of GitHub, clearly outlines some advantages of this approach:

• The project is better executed as you have time to think through every aspect before implementation.
• It’s much easier to write documentation at the beginning of the project when your mind is fresh and ideas are easier to put in writing.
• When you (or your team) start implementing the API, there’s a clear specification to follow.
• Discussing ideas and possible changes is much easier when there’s written documentation.

While acknowledging these benefits is easy, what’s not so easy is to start from scratch. Looking at a blank screen thinking about what endpoints your API should have doesn’t help you progress with the documentation. This article helps you bypass that initial blank state by highlighting API documentation sections and suggesting best practices that you can incorporate into your own design. We’ll go into more detailed examples, but let’s first start by looking at what components any API documentation absolutely should have.

Fundamental API Documentation Sections #

These are the sections that every API documentation should offer. Without these sections consumers will have a very hard time understanding how your API can be used, and, in many cases, they will simply give up.

• Authentication information, describing which authentication scheme your API uses. If you’re using OAuth, don’t forget to explain how to setup an OAuth application and obtain the API Key and Secret.
• Errors and how they’re communicated to API consumers. Here you should explain if you follow any error standard, e.g., the HTTP Status Codes, and how errors are generally communicated inside responses.
• Endpoints and information on how to consume them, including requests and responses. This is considered the main section where you expose all your API methods, explain how they can be reached, and note what kind of parameters are allowed.

With these three sections you’re off to a great start because you’ve already documented most of what is needed to consume your API and your offering. But, as you’re about to find out, this is often not enough. As you obtain more sophisticated consumers, you’ll end up having to offer them documentation on non-functional aspects of your API.

Expert API Documentation Sections #

Incorporating the following points will make your API stand out from the competition. While it’s true that some consumers may neglect these particular sections, business-oriented consumers may consider these to be imperative.

• Terms of Use, including API Limits and other best practice terms and conditions. Permissions and constraints need to be clearly stated so that consumers understand what API usage practices are allowed.
• Examples of how to consume your API, including starting from scratch but also displaying use cases where your API would come in handy. Include plenty of code and, if possible, case studies with actual API consumers and example applications.
• A Changelog detailing latest updates and how they might affect API consumers. This will help consumers gauge the stability of the API and help them understand if any changes made to the API calls might impact their integration.

Including these sections will put your API documentation in a much better position. Now, when potential consumers view your API, they will find it clearly documented. Increasing awareness with peripheral API information helps establish credibility, decreases onboarding issues, and helps to build trust in the long term.

But saying is easier than doing. How do you move from an initial blank state to well-structured documentation? Read on and see how the following templates can be used to craft tasty API documentation.

3 API Documentation Template Resources #

Among all the API documentation formats, three of them deserve a mention because they let you design your API in a way that can be easily consumed by humans as well as machines:

• Swagger: Developed by Reverb Technologies, lets you easily generate your own API server code, client code and also the documentation itself.
• RAML: Created by MuleSoft, offers an easy way to specify an API by using patterns.
• API Blueprint: Maintained by Apiary, it’s a standard based on the popular Markdown format that lets you easily generate code from the documentation.

Basic Documentation Using API Blueprint #

Apiary has put together several API Blueprint examples that can help document an API without having to start from scratch. API Blueprint is a straightforward, uncomplicated way of documenting APIs that uses Markdown as its format language. API Blueprint files can then be read directly and converted to HTML, PDF or any other documentation friendly format. Another advantage of using API Blueprint is that the same file can also be manipulated directly by more than a dozen useful tools, including code generation, which helps you follow the “Documentation Driven Design” approach explained before.

Let’s take a look at some of the examples, starting from a very simple one and growing in sophistication as we progress. This first example (some parts removed by me) doesn’t offer all the required sections I mentioned before, but it’s a quick way for you to get acquainted to the API Blueprint format.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

FORMAT: 1A

# Named Resource and Actions API  
This API example demonstrates how to name a resource and its actions (...).

# My Message [/message]  
Note the URI `/message` is enclosed in square brackets.

## Retrieve a Message [GET]  
This action clearly retrieves the message.

+ Response 200 (text/plain)

        Hello World!

## Update a Message [PUT]  
`Update a message` - nice and simple naming is the best way to go.

+ Request (text/plain)

        All your base are belong to us.

+ Response 204

The above documentation starts by describing what the API offers to consumers. It goes on to describe one endpoint (/message) and includes its possible operations. As you can see, the /message endpoint lets you retrieve a message by performing an HTTP GET request and also lets you update a message by performing an HTTP PUT operation. The documentation also shows what the expected requests and responses are for each operation.

Increased Sophistication Using API Blueprint #

Now that you’ve seen a simple API Blueprint example in action, let’s work through a more complete case, where authentication and error information is also present. Let’s start by looking at the API description:

## Gist Fox API  
Gist Fox API is a **pastes service** similar to [GitHub’s Gist](http://gist.github.com).

General information is given about what the API can be used for. Next, authentication is described:

## Authentication  
*Gist Fox API* uses OAuth Authorization. First you create a new (or acquire existing) OAuth token using Basic Authentication. After you have acquired your token you can use it to access other resources within token' scope.

As you can see, this API uses OAuth and explains what you as a consumer would have to do to obtain an OAuth token and how API resources can be consumed after you have it. What follows lays out the error standards:

## Error States  
The common [HTTP Response Status Codes](https://github.com/for-GET/know-your-http-well/blob/master/status-codes.md) are used.

The API follows the HTTP Status Codes standard, informing the consumer of what to expect when consuming the available endpoints. As error returns follow a well known standard there’s no need to explain in further detail how it works (nonetheless, the link to GitHub’s HTTP status list is helpful). Let’s now look at how an API endpoint is documented:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

## Star [/gists/{id}/star{?access_token}]  
Star resource represents a Gist starred status.

The Star resource has the following attribute:

- starred

+ Parameters  
    + id (string) ... ID of the gist in the form of a hash  
    + access_token (string, optional) ... Gist Fox API access token.

This section defines the Star resource and its attributes, and tells the consumer what parameters can be passed to this resource for authentication – in this case an id and an access token because OAuth is being used. The next body describes the resource’s underlying model:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

+ Model (application/hal+json)

    HAL+JSON representation of Star Resource.

    + Body

            {  
                "_links": {  
                    "self": { "href": "/gists/42/star" },  
                },  
                "starred": true  
            }

This section uses Hypertext Application Language (HAL), to specify the resource data model. This gives the API provider great flexibility to document in detail the information that a given resource is able to handle. Let’s now look at one of the possible operations on the star resource:

### Star a Gist [PUT]  
This action requires an `access_token` with `gist_write` scope.

+ Response 204

This operation is performed by issuing an HTTP PUT operation to the star resource, which is available at /gists/{id}/star{?access_token}, as described before. It explains how the operation can be accessed and what is an expected response: in this particular case, you’ll need a valid access token and you can expect to receive an HTTP 204 response, meaning that the server has fulfilled the request but there’s nothing to reply back.

As these are two basic examples of what you can do with API Blueprint, I recommend you take a look at all you can do with it by opening the links shared in this article.

Conclusion #

Everyone agrees that documentation is an absolute must if you want to guarantee that your API is well understood by potential consumers and business partners. While some people believe that starting an API project with initial documentation it is a good idea, most people struggle to actually write something. In this article you’ve learned the advantages of following a “Documentation Driven Design” approach as well as the most important sections you don’t want to forget.

As starting from scratch is the real problem for most people, this article shared some templates that you use in your project to quickly help you get started. By following the mentioned API Blueprint examples you’ll not only have something to start with, but you’ll also be following the best practices in terms of documentation. After you finish your documentation you can quickly generate the code for your API using the API Blueprint tools.