13. Document the API Design
Documentation is the third user interface for APIs, and the most important.
D. Keith Casey
Figure 13.1 The final step in the Refine Phase is to produce robust documentation, incorporating learnings back into the API design.
Documentation is a very important element of the developer experience. Most API teams assume that reference documentation for each operation is sufficient. However, that is only the beginning of the API documentation effort.
Establishing an API documentation strategy is part of API design. Developer portals must support a variety of personas that all contribute to the success of an API. This chapter outlines the essentials of any API documentation effort and provides insights from the field on how to establish and improve an API developer portal.
The Importance of API Documentation
API documentation is the most important user interface for developers that will integrate the API. It is the primary communication medium between the API provider, tasked with designing and delivering the API, and the many developers that will integrate the API into applications and automation scripts.
Unless the API is part of an open-source product, API consumers will never have access to the source code. Even if access to the source code is possible, reading code to understand an API is unacceptable. It slows down the developer. At best, this causes frustration. At worst, they move on to a competitor or build the required functionality themselves.
Additionally, organizing the API documentation is important. By creating clear areas for getting started guides and reference documentation, developers can locate exactly what they need when they need it. Even the most well-written API documentation suffers if it isn’t organized properly into a developer portal.
Principle #4: API documentation is the most important user interface for developers
It is the primary communication medium between the API provider, tasked with designing and delivering the API, and the many developers that will integrate the API into applications and automation scripts. Therefore, API documentation should be first class and not left as a last-minute task.
API Description Formats
Traditionally, technical documentation was captured and shared in PDF, Microsoft Word documents, or plain HTML. While these formats are better than no documentation at all, they limit the usefulness of the documentation to human consumption.
API description formats provide the details of an API in machine-readable format. Tools may convert the description into human-readable documentation, generate client-side libraries, and produce a skeleton of server-side code with common patterns and practices already established.
Some API description formats support adding vendor-specific extensions. These may be used to further define authorization, routing, and configuration rules for use in automating deployment processes and API management layer configuration.
API styles such as GraphQL and gRPC provide their own respective formats. For REST-based or RPC-based APIs that are built directly on top of HTTP, a separate description format is needed. This section provides an overview of popular formats to help teams select the format or formats that teams would like to use to drive their API description and documentation efforts.
Documentation examples are available in the API workshop examples repository available on GitHub.
OpenAPI Specification (OAS)
Formerly known as Swagger, the OpenAPI Specification (OAS) is currently one of the most popular formats for describing the details for an API. It is managed by the Linux Foundation under the stewardship of the OpenAPI Initiative (OAI). The Swagger brand is now owned by Smartbear, which continues to maintain and support various open-source API projects under the Swagger name.
OAS came into popularity due to the try-it-out feature that is built into the SwaggerUI project. This project was designed to generate HTML-based API reference documentation for developers. The try-it-out feature allows developers and non-developers to explore an API against a live server from within the generated documentation. It supports JSON and YAML-based formats.
OAS is currently in version 3 of the specification, although OAS v2 is still encountered in some organizations and open-source projects. The tools ecosystem is vast and continues to grow, making this a popular choice for teams building their first or 31st API. An example of OAS v3 is provided in Listing 13.1, based upon the API design for the Shopping Cart API created in Chapter 7.
Listing 13.1 An example of OpenAPI Specification v3
openapi: 3.0.0 info: title: Bookstore Shopping Example description: The Bookstore Example REST-based API supports the shopping
experience of an online bookstore. The API includes the following capabilities
and operations... contact: { } version: '1.0' paths: /books: get: tags: - Books summary: Returns a paginated list of books description: Provides a paginated list of books based on the search
criteria provided... operationId: ListBooks parameters: - name: q in: query description: A query string to use for filtering books by title
and description. If not provided, all available books will be listed... schema: type: string responses: 200: description: Success content: application/json: schema: $ref: '#/components/schemas/ListBooksResponse' 401: description: Request failed. Received when a request is made
with invalid API credentials... 403: description: Request failed. Received when a request is made
with valid API credentials towards an API operation or resource you do not
have access to. components: schemas: ListBooksResponse: title: ListBooksResponse type: object properties: books: type: array items: $ref: '#/components/schemas/BookSummary' description: "A list of book summaries as a result of a list or
filter request..." BookSummary: title: BookSummary type: object properties: bookId: type: string description: An internal identifier, separate from the ISBN,
that identifies the book within the inventory isbn: type: string description: The ISBN of the book title: type: string description: The book title, e.g. A Practical Approach to API
Design authors: type: array items: $ref: '#/components/schemas/BookAuthor' description: '' description: "Summarizes a book that is stocked by the book store..." BookAuthor: title: BookAuthor type: object properties: authorId: type: string description: An internal identifier that references the author fullName: type: string description: The full name of the author, e.g. D. Keith Casey description: "Represents a single author for a book. Since a book
may have more than one author, ..."
API Blueprint
API Blueprint originated by an API tools vendor called Apiary, now a part of Oracle. It combines the idea of easy documentation generation using Markdown with a structure that makes it machine-readable for supporting code generation and other tooling needs.
Since API Blueprint is based on Markdown, any tool capable of rendering and editing files using the Markdown format, including developer IDEs, is able to work with this format. While the ecosystem of tooling isn’t as vast as OAS, it does have considerable community support due to the pre-acquisition efforts of Apiary. As Listing 13.2 shows, it is easy to work with and therefore a popular choice for those seeking to combine Markdown-based documentation alongside a machine-readable API description format.
Listing 13.2 An example of API Blueprint
FORMAT: 1A HOST: https://www.example.com # Bookstore Shopping API Example The Bookstore Example REST-based API supports the shopping experience of
an online bookstore. The API includes the following capabilities and
operations... # Group Books ## Books [/books{?q,offset,limit}] ### ListBooks [GET] Provides a paginated list of books based on the search criteria provided... + Parameters + q (string, optional) A query string to use for filtering books by title and
description. If not provided, all available books will be listed... + offset (number, optional) - A offset from which the list of books are retrieved, where an
offset of 0 means the first page of results... + Default: 0 + limit (number, optional) - Number of records to be included in API call, defaulting to 25
records at a time if not provided... + Default: 25 + Response 200 (application/json) Success + Attributes (ListBooksResponse) + Response 401 Request failed. Received when a request is made with invalid API
credentials... + Response 403 Request failed. Received when a request is made with valid API
credentials towards an API operation or resource you do not have access
to. # Data Structures ## ListBooksResponse (object) A list of book summaries as a result of a list or filter request... ### Properties + `books` (array[BookSummary], optional) ## BookSummary (object) Summarizes a book that is stocked by the book store... ### Properties + `bookId` (string, optional) - An internal identifier, separate from the
ISBN, that identifies the book within the inventory + `isbn` (string, optional) - The ISBN of the book + `title` (string, optional) - The book title, e.g. A Practical Approach to API Design + `authors` (array[BookAuthor], optional) ## BookAuthor (object) Represents a single author for a book. Since a book may have more than one
author, ... ### Properties + `authorId` (string, optional) - An internal identifier that references
the author + `fullName` (string, optional) - The full name of the author, e.g. D.
Keith Casey
RAML
RAML stands for RESTful API Modeling Language and was designed with the full API design lifecycle in mind. It originated within Mulesoft but included contributors from many other industry leaders. The design of RAML was intended to support design tooling alongside documentation and code generation tools. RAML is built upon the YAML format.
While RAML originated with the help of Mulesoft, the specification and much of the tooling is vendor neutral. RAML focuses on describing resources, methods, parameters, responses, media types, and other HTTP constructs common to REST-based APIs. However, it can be used to describe nearly any HTTP-based API format.
Listing 13.3 An example of RAML v1.0
#%RAML 1.0
title: Bookstore Shopping API Example
version: 1.0
baseUri: https://www.example.com
baseUriParameters:
defaultHost:
required: false
default: www.example.com
example:
value: www.example.com
displayName: defaultHost
type: string
protocols:
- HTTPS
documentation:
- title: Bookstore Shopping API Example
content: The Bookstore Example REST-based API supports the shopping
experience of an online bookstore. The API includes the following
capabilities and operations...
types:
ListBooksResponse:
displayName: ListBooksResponse
description: A list of book summaries as a result of a list or filter
request...
type: object
properties:
books:
required: false
displayName: books
type: array
items:
type: BookSummary
BookSummary:
displayName: BookSummary
description: Summarizes a book that is stocked by the book store...
type: object
properties:
bookId:
required: false
displayName: bookId
description: An internal identifier, separate from the ISBN, that
identifies the book within the inventory
type: string
isbn:
required: false
displayName: isbn
description: The ISBN of the book
type: string
title:
required: false
displayName: title
description: The book title, e.g. A Practical Approach to API
Design
type: string
authors:
required: false
displayName: authors
type: array
items:
type: BookAuthor
BookAuthor:
displayName: BookAuthor
description: Represents a single author for a book. Since a book may
have more than one author, ...
type: object
properties:
authorId:
required: false
displayName: authorId
description: An internal identifier that references the author
type: string
fullName:
required: false
displayName: fullName
description: The full name of the author, e.g. D. Keith Casey
type: string
/books:
get:
displayName: ListBooks
description: Provides a paginated list of books based on the search
criteria provided...
queryParameters:
q:
required: false
displayName: q
description: A query string to use for filtering books by title
and description. If not provided, all available books will be listed...
type: string
offset:
required: false
default: 0
example:
value: 0
displayName: offset
description: A offset from which the list of books are retrieved,
where an offset of 0 means the first page of results...
type: integer
minimum: 0
format: int32
limit:
required: false
default: 25
example:
value: 25
displayName: limit
description: Number of records to be included in API call,
defaulting to 25 records at a time if not provided...
type: integer
minimum: 1
maximum: 100
format: int32
headers:
Authorization:
required: true
displayName: Authorization
description: An OAuth 2.0 access token that authorizes your app to
call this operation...
type: string
responses:
200:
description: Success
headers:
Content-Type:
default: application/json
displayName: Content-Type
type: string
body:
application/json:
displayName: response
description: Success
type: ListBooksResponse
401:
description: Request failed. Received when a request is made with
invalid API credentials...
body: {}
403:
description: Request failed. Received when a request is made with
valid API credentials towards an API operation or resource you do not have
access to.
body: {}
JSON Schema
The JSON Schema specification offers a machine-readable format for capturing the structure and validation rules for JSON-based structures. The specification is divided into core foundational rules and validation rules, making it a comprehensive solution for defining JSON schemas that require validation. JSON Schema can be thought of as the JSON equivalent to XML Schema.
While independent of any one API style, JSON Schema may be used to describe resource representations for REST-based APIs and other API styles. It is also found in organizations as a single format for defining schema formats for domain objects across the enterprise.
While the schema definition portion of OAS is quite flexible, it lacks some of the robust definition support offered by JSON Schema. Recent efforts with OAS v3.1 have helped to bring JSON Schema and OAS in alignment to allow for the use of both formats. Expect JSON Schema to continue gaining tooling support moving forward given its acceptance within the OAS description format.
Listing 13.4 An example JSON Schema
{
"$id": "https://example.com/BookSummary.schema.json",
"$schema": "http://json-schema.org/draft-07/schema#",
"description": "Summarizes a book that is stocked by the book store...",
"type": "object",
"properties": {
"bookId": {
"type": "string"
},
"isbn": {
"type": "string"
},
"title": {
"type": "string"
},
"authors": {
"type": "array",
"items": {
"$ref": "#/definitions/BookAuthor"
}
}
},
"definitions": {
"BookAuthor": {
"type": "object",
"properties": {
"authorId": {
"type": "string"
},
"fullName": {
"type": "string"
}
}
}
}
}
API Profiles Using ALPS
Application-Level Profile Semantics (ALPS) is a description format for defining application-level and domain semantics, independent of the API style(s) and protocol(s) available. It helps to define a profile of the digital capabilities and messages exchanged for an API rather than the specifics of how to interact with it. ALPS is a machine-readable format that is useful for capturing API profiles produced during API modeling (detailed in Chapter 6).
ALPS was designed to power API and service discovery, API catalogs, and tooling metadata where an API profile may be implemented using one or multiple API styles including REST-based, gRPC, and/or GraphQL. The specification provides support for XML, JSON, and YAML formats.
ALPS supports the combination of two fundamental elements: data (the message) and transitions (operations). When combined, these two elements capture the operational and message semantics for an API profile. The default format for ALPS is XML, though an JSON-based specification is planned.
Listing 14.5 provides an example API profile that could be used to describe the operations and messages for any number of API style implementations that are available.
Listing 13.5 An example API profile in XML using the ALPS Draft 02 format
<alps version="1.0">
<doc format="text">A contact list.</doc>
<link rel="help" href="http://example.org/help/contacts.html" />
<!-- a hypermedia control for returning BookSummaries -->
<descriptor id="collection" type="safe" rt="BookSummary">
<doc>
Provides a paginated list of books based on the search criteria
provided.
</doc>
<descriptor id="q" type="semantic">
<doc>A query string to use for filtering books by title and
description.</doc>
</descriptor>
</descriptor>
<!-- BookSummary: one or more of these may be returned -->
<descriptor id="BookSummary" type="semantic">
<descriptor id="bookId" type="semantic">
<doc>An internal identifier, separate from the ISBN, that identifies
the book within the inventory</doc>
</descriptor>
<descriptor id="isbn" type="semantic">
<doc>The ISBN of the book</doc>
</descriptor>
<descriptor id="title" type="semantic">
<doc>The book title, e.g. A Practical Approach to API Design</doc>
</descriptor>
<descriptor id="authors" type="semantic" rel="collection">
<doc>Summarizes a book that is stocked by the book store</doc>
<descriptor id="authorId" type="semantic">
<doc>An internal identifier that references the author</doc>
</descriptor>
<descriptor id="fullName" type="semantic">
<doc>The full name of the author, e.g. D. Keith Casey</doc>
</descriptor>
</descriptor>
</descriptor>
</alps>
Improving API Discovery Using APIs.json
There are multiple API description formats that may be necessary to help developers consume the API using various tools. APIs.json is a description format that assists in API discovery through a machine-readable index file. It is similar to a site map for a website that helps direct search engine indexers to important areas of the website.
A single APIs.json file may reference multiple APIs, making this format useful for bundling multiple, separate API description files into a single product or platform view. When combined with other machine-readable formats, APIs may be discovered, indexed, and made available within public or private API catalog.
As the name indicates, the default format is JSON although the YAML-based format, shown in Listing 14.6, is also available.
Listing 13.6 An example APIs.json that offers an indexed view of an API and its various machine-readable description files
name: Bookstore Example type: Index description: The Bookstore API supports the shopping experience of an
online bookstore, along with ... tags: - Application Programming Interface - API created: '2020-12-10' url: http://example.com/apis.json specificationVersion: '0.14' apis: - name: Bookstore Shopping API description: The Bookstore Example REST-based API supports the shopping
experience of an online bookstore humanURL: http://example.com baseURL: http://api.example.com tags: - API - Application Programming Interface properties: - type: Documentation url: https://example.com/documentation - type: OpenAPI url: http://example.com/openapi.json - type: JSONSchema url: http://example.com/json-schema.json contact: - FN: APIs.json email: [email protected] X-twitter: apisjson specifications: - name: OpenAPI description: OpenAPI is used as the contract for all of our APIs. url: https://openapis.org - name: JSON Schema description: JSON Schema is used to define all of the underlying
objects used. url: https://json-schema.org/ common: - type: Signup url: https://example.com/signup - type: Authentication url: http://example.com/authentication - type: Login url: https://example.com/login - type: Blog url: http://example.com/blog - type: Pricing url: http://example.com/pricing
Extending Docs with Code Examples
Code examples provide the important guidance necessary for developers to be able to apply the documentation in practice. They are the glue that helps connect-the-dots between reference documentation and developers integrating the API.
Code examples come in a variety of forms, from just a few lines that demonstrate how a specific operation works, to more complex examples that demonstrate a complete workflow.
Write ‘Getting Started’ Code Examples First
Initially, the developer must overcome basic understanding of the API and how it will help solve their problem. It is important to remember that during this phase, the developer just wants to see something work.
“Time to First Hello World”, or TTFHW, is a key metric for determining API complexity. The longer it takes to get a developer to their first “win”, the more likely the developer will struggle with the API and perhaps abandon it or build their own solution.
To help developers get started quickly, provide concise examples that remove the need for explicit coding. Look at the following example from Stripe:
require "stripe"
Stripe.api_key = "your_api_token"
Stripe::Token.create(
:card => {
:number => "4242424242424242",
:exp_month => 6,
:exp_year => 2024,
:cvc => "314"
})
Notice in this example that there is no code to write. The developer only needs to fill-in their API key they are able to obtain a credit card token in their sandbox environment.
Example code that requires developers to write lots of code should be avoided at this stage to achieve a lower TTFHW. Never require developers to write code to complete an example when first trying out the API. Instead, make it easy to get started and see the request work successfully.
Expanding Documentation with Workflow Examples
After the developers have had some time to try the API using some code examples, the next step is to begin to demonstrate common use cases and workflows.
Workflow examples focus on achieving specific outcomes. These examples must offer complete understanding over production-ready coding conventions. The use of inline comments is helpful to explain why each step is necessary. Use hard-coded values for better understanding. Choose variable and method names that make the code easy to read.
Below is an example of charging a credit card using Stripe’s Ruby-based helper library:
# Remember to change this to your API key Stripe.api_key = "my_api_key" # Token is created using Stripe.js or Checkout! # Get the payment token submitted by the form: token = params[:stripeToken] # Create a Customer: customer = Stripe::Customer.create( :email => "[email protected]", :source => token, ) # Charge the Customer instead of the card: charge = Stripe::Charge.create( :amount => 1000, :currency => "usd", :customer => customer.id, ) # YOUR CODE: Save the customer ID and other info # in a database for later. # YOUR CODE (LATER): When it's time to charge the # customer again, retrieve the customer ID. charge = Stripe::Charge.create( :amount => 1500, # $15.00 this time :currency => "usd", :customer => customer_id, # Previously stored, then retrieved )
Note that workflow code examples will be more complex than those used to achieve a quick TTFHW. These examples need to be short enough to explain the concepts but not too long that they require considerable time to understand. It is often best to demonstrate scenarios that are easily understood and likely map to customer needs.
Error Case and Production Ready Examples
While some developers may be more familiar with making their code production ready, it is always helpful to provide assistance during the last mile of API integration. This will help developers understand how to integrate the API into their production environment.
These examples should help developers properly troubleshoot problems and incorporate retry loops when an API outage occurs. Adding examples that demonstrate how to catch and recover from bad data provided by end users is also important. Finally, show how to obtain the current rate limits for their account and detect when rate limits have been exceeded.
From Reference Docs to a Developer Portal
API documentation is used as a general term for describing an API and how to use it. as if there is only one kind of documentation. However, there is more to API documentation than just the reference docs. It requires having a developer portal that pulls together all of the elements that API consumers will need to be successful. It also addresses additional personas, beyond the developer, that participate in the API adoption process.
Increasing API Adoption Through Developer Portals
While developers are often the target persona for an API developer portal, there are other personas that benefit from a developer portal.
Other personas that benefit from developer portals include:
■ Executives involved in the process of discovering, reviewing, and approving a new API
■ Business and product managers searching for ways to leverage internal and/or third-party APIs to speed delivery of new solutions
■ Solution architects and tech leads that are defining a new solution that may leverage existing APIs from an enterprise portfolio
A developer portal helps bring together the different styles of communication that are needed to ensure that APIs can be found, the benefits of using the API understood, and assistance provided to developers on how to integrate the API. It also provides the interface on top of the many faceless APIs that exist within an organization’s API portfolio for evangelism across the organization.
Case Study: Enterprise Developer Portal Success
An API program initiative for a large enterprise IT group started with just a few key people. After a year of investment, the team had produced several APIs that offered a number of high-value capabilities to the business. However, the team produced only reference documentation—no developer portal. As a result, information about how to start using the API wasn’t readily available. With help, the team expanded the reference documentation into a complete developer portal.
Their revised developer portal guides developers through an introduction to the API’s structure and capabilities, onboarding in a sandbox environment for integration, and production access through a lightweight certification program.
Influential executives use the developer portal to evangelize the API program throughout the organization, resulting in increased demand for adopting APIs. The developer portal now serves as a central communication tool and a method of promoting the program to technical and non-technical teams.
Elements of a Great Developer Portal
A great developer portal consists of the following elements that address the needs of the variety of personas involved in adopting an API:
■ Feature Discovery: Provides an overview of the API, addressing concerns such as benefits, capabilities, and pricing to qualify prospects.
■ Case studies: Case studies highlight applications that have been built using the API. This helps the reader understand how the API is used within their specific vertical business domain or for specific types of app
■ Getting started guides: Introduces developers to common use cases that the API solves along with a step-by-step guide for getting started for each case. Sometimes referred to as a quick start guide
■ Authentication and authorization: Describes how to obtain an API token with the appropriate authorization scopes necessary to use the API as desired
■ API reference documentation: Details on each operation including URL path structures, input and output data structures, and error data structures
■ Release Notes and changelog: Summarizes the changes in each release, including new operations and enhancements to existing operations in a historical format
Beyond these essential elements, developer portals seek to inform and deliver on the following experiences:
■ Easy Onboarding – APIs rarely gain adoption if it is difficult to get started. Easy onboarding, from self-registration to a guided tour and API token creation will help developers overcome the challenges to adopting a new API. Integration between the developer portal and the API gateway that is responsible for provisioning API tokens is important to make this effective.
■ Operational Insight – Is the API available or temporarily down? A simple status page that reflects an API’s availability will help to inform developers and operations staff that see increased errors in their applications.
■ Live Support – Including a chat solution, whether embedded into the developer portal or through a communication platform, such as Slack, Webex, or Microsoft Teams, will help provide direct access to those that can help resolve integration. The team responsible for this is often called developer relations, or DevRel for short. They might be responsible for the developer portal alongside developer support.
Effective API Documentation
To write better documentation, it is important to answer the questions common for those considering the adoption of an API. The answers to these questions may be obtained through interviews conducted with developers integrating the API.
It is important to engage in conversations with them whenever possible. Engaging in discussions with API consumers will lead to those critical ‘aha!’ moments that API providers need to improve their documentation.
When this isn’t possible, try to find other developers to review the documentation. Conduct a documentation audit by defining a mythical scenario, then writing some code to call the API to produce a prototype. Along the way, ask questions to identify areas of improvement for the API documentation offered.
Question #1: “How does your API solve my problems?”
Ensure that the API documentation has an introduction that covers what the API solves, what it doesn’t solve, and example use cases that it has solved in the past. This will help establish a context for the reader, who may be trying to decide if the API is the right fit for their need.
Question #2: “What problem does each API operation support?”
Add documentation to clarify what each operation does and when it may be applicable. An API operation with the description of “Gets all accounts” is not helpful. Add additional details about what kinds of filters, implied or explicit, are supported.
Offer some example scenarios when an API operation may be used or how it may be combined with other operations to achieve particular outcomes. The job stories and API profiles created during the ADDR Process is a good source for this detail.
Question #3: “How do I get started using the API?”
If the API does offer self-service onboarding, call this out in the documentation as a benefit to getting started faster. For those that require time to go through a partnership program, include this in the documentation as well. This will ensure that the appropriate lead time is factored in prior to developers beginning the first ‘hello world’ integration.
It is important to offer links to the onboarding process in various locations of the API documentation. Not all developers start from the homepage of the developer portal. Reference documentation that is publicly accessible will be indexed by search engines, creating organic entry points into a developer portal. Be sure to include a link to the onboarding process somewhere near the top of reference API documentation.
Finally, don’t assume that all developers can “figure out” how to use an API. Every developer is at a different stage in their career. Some may have the same, more, or less experience than others using web APIs. Take the time to explain, step-by-step, how to get started.
The Role of Technical Writer in API Docs
Traditionally, technical writers focused on delivering manuals for software, often in PDF or HTML format. These manuals consisted of screenshots and step-by-step guidance for using software. Extensive knowledge of the user interface, including features that are often overlooked, was required. The role was critical for ensuring end-users were able to use the software effectively and efficiently while reducing support costs. Rarely, technical writers to have a deep knowledge of one or more programming languages, such as C/C++, Java, or Python.
Over the past decade, the role of technical writers has undergone a transition. For some organizations, technical writers have been replaced with user experience (UX) experts that design user interfaces that require minimal or no documentation. Technical writers were replaced by marketing and product roles that improve the copy of an app to encourage conversion or increased usage metrics.
With the growth of APIs, technical writers are in heavy demand. They are required to understand how to use APIs directly via HTTP, along with a variety of programming languages to demonstrate API integration using Java, Python, GoLang, Ruby, JavaScript, ObjectiveC, Swift, command-line automation, and more. Their target audience spans end-users, experienced developers, and developers right out of university. Rather than documentation efforts focused on a few large releases per year, now releases may occur on a weekly or daily basis due to deployment automation and cloud infrastructure.
The value that technical writers offer to any product is enormous. For APIs, their talent is invaluable. They provide an outside-in perspective on an API’s design and documentation to ensure it provides value to the target audience. Questions around the purpose and intended use of each API operation help to hone the API design early.
The challenge for most technical writers is building a sufficient team to handle the vast amount of work before, during, and after every release of every API offered by the organization. A single technical writer for a small API may be able to keep documentation updated. If the organization is large and offers multiple APIs, perhaps even API products, the challenge increases beyond the capabilities of even the most talented technical writer.
Therefore, it is critical that organizations have a team of technical writers. This team should be able to dedicate a few technical writers for emerging APIs while others are focused on maintaining documentation for existing APIs. They must be considered in all API design decisions early and should be part of any API design process from start to finish. All decisions regarding API documentation tools and process should be made by the technical writers, not by developers forcing specific tools upon them. They should be considered first-class team members rather than a siloed team that have API implementations thrown at them at the last minute for a quick-and-dirty documentation effort.
Finally, remember that API documentation is the user interface for developers. Technical writers can make or break an API’s success. The same can be said for enterprise API platforms where some APIs are targeting partners, customers, and third-party service integrators.
The Minimum Viable Portal (MVP)
The Minimum Viable Portal (MVP) builds upon the idea of the minimal viable product idea from lean processes to establish a phased approach to delivering a developer portal. The MVP provides prioritization as three phases, the first being the minimal developer portal needs. As the team matures the API, the developer portal may be enhanced by taking it from minimal documentation to a robust developer portal.
Phase 1: Minimal Viable Portal (MVP)
The checklist in Table 14.1 includes the five most important modules to include in an initial API developer portal. Included are questions to answer and information to include in each section to help guide the process.
Table 14.1 A Minimal Viable Portal Checklist
Once all items on this list are checked off for all sections, the API developer portal is in good shape to support the needs of initial consumers involved in the early stages of API design, as well as future consumers that may discover the API. Depending on available expertise and the number of API operations, the effort required to complete this phase may take between one and three weeks. If necessary, focus on the most common use cases that the API addresses, then incorporate additional documentation in future phases.
Phase 2: Improvement
The best place to spend time improving the portal will depend on the characteristics of the API. If the API has changed, has new operations, or works differently than previously documented, the first priority is updating the docs to incorporate the changes. But if everything is up to date, consider some of these ideas in Table 14.2 based on the time available.
Table 14.2 Improving the developer portal
Phase 3: Focusing on Growth
Once the items from the first two phases that are relevant to team needs have been completed, consider a few additional improvements to shift the portal from supporting customers to generating growth in adoption:
■ Add Case Studies: Case studies demonstrate an API’s value by describing how clients have used it to solve a problem, expand business, or succeed in some way. They add depth and meaning to API documentation by offering real-world context, which helps readers understand how the API has already benefitted others and could benefit them too. Case studies can even inspire new ideas for using an API. If “Case Studies” sounds a little dry or academic, try something like “Success Stories” or “Client Stories” instead.
■ Add “Getting Started” Guides: Readers who understand how APIs work might be able to start using an API with authentication details alone, but what about users who aren’t as comfortable? A getting started guide should build users’ confidence that they can use the API and inspire them to dig deeper into the rest of the documentation.
■ Incorporate Analytics: Adding analytics to the portal help portal administrators tailor it to the needs of the audience based on real data about traffic patterns and help readers move more smoothly through the content.
■ Move to Single-Page Format: Consider restructuring some portions of the portal on a single page. The benefit of this format is that users can navigate the documentation either with the menu that links to all the section headings or by using Ctrl/Cmd+F to search for text on the page.
■ Translate the Docs: As the API gains traction, consider whether documentation translation would be helpful. Professional translation is expensive and takes time, so a clear and persuasive business case is necessary before starting this journey. It’s rare, but some teams discover that most of their users are in another country therefore would benefit in translated docs.
Finally, continually check around to see what other companies with successful APIs are doing with their docs. Then produce a plan for incorporating these new ideas into the developer portal to benefit customers, partners, and internal developers.
Tools and Frameworks for Developer Portals
One of the challenges of establishing a developer portal is to select a tool, or series of tools, that help produce the developer portal. Outlined below are tools organizations have used to produce their developer portal:
■ Static site generators: Tools such as Jekyll, used to power GitHub pages, and Hugo are popular choices for creating and managing developer portals. Pages are authored using Markdown or similar notation and stored in a code repository. Deployment is typically automated to ensure the latest version of the documentation is published once changes are merged into the main branch.
■ SwaggerUI: This is the tool that started it all for the Swagger API description format, now separated from the tool as the OpenAPI Specification. This is an open source codebase that will render any OAS v2 or v3 specification, plus older Swagger specification files, into API reference docs in HTML format.
■ MVP Template: I have collaborated with others to create a GitHub project for starting an API developer portal called the Minimum Viable Portal (MVP) that is based in Jekyll. It helps to combine the static site generator with some placeholders for content and integrating SwaggerUI or similar reference docs into a single location. Fork the repo at https://github.com/launchany/mvp-template and customize as needed to get started quickly.
Whatever tools selected, be sure to provide any machine-readable descriptions, such as OpenAPI Specification files, as part of the portal. This will allow developers to apply their own tooling, such as custom code generators, for speeding up the integration process.
Finally, be sure to do research into open source and commercial tools, either on-premises or SaaS-based offerings, that is able to assist in the creation and management of the developer portal. Some API management layers (APIMs) offer portal management support as well.
Summary
Establishing an API documentation strategy is part of delivering a successful API product, formalized API program, or enterprise API platform. Developer portals must support a variety of personas. It is critical to ensure that documentation is part of the overall API design and delivery lifecycle. Otherwise, it becomes a last-minute task that results in poor documentation that fails to meet the needs of the target personas.
Seek to include documentation and API portal updates as part of the overall delivery schedule. An API should be considered done only when the documentation is updated alongside the release. This will produce a more complete API that encourages rapid adoption by developers and other decision makers.