6 things to prepare when writing API Specification Document

fariz mamad
5 min readNov 4, 2021

--

I have a bad experience when leading a development project, which was when the back-end developers and UI developers were debating about the API contract. We have already made request and response contracts in a meeting. However, when the contracts were implemented, they were not match. Why? Because they were not documented!

taken from https://medium.com/evodeck/why-you-should-write-api-documentation-2bca47574753

There are ways to solve this problem. You may choose to make a protocol buffer to present the contract. However, if your team is not ready yet to use that mechanism, you can choose simple yet powerful and ubiquitous method like API Specification Document.

Companies with publicly available software usually present API Specification document for developers who want to integrate their system to the companies’ software. So, it should be easy to follow their practices.

On my journey to learn writing this document, there are 6 (or more) things to prepare. I have summarized them in the following sections. So, stay tune and scroll down!

1. Format & tools

You may choose the format which fit to your writing requirements. You may choose it yourself, or follow the best practice used by another company. Since you have read this far, I have prepare my suggestions.

Language — English
At least your document is written in common language such as English. After that, you can translate it into another language of interest.

Format — Word/Markdown/OpenAPI
With word-based format, you can write any document with lovely user interface on tools like Microsoft Word or Google Docs. However, it is hard to format the texts like coloring and code style.

With markdown format, styling the texts for coloring and code is very easy. Use a pair of triple backtick (```) and give the programming file format/language name, then the style is automatically applied. Markdown format also supported in documentation server such as MkDocs. Use dillinger.io as your editor, which is free as I write this article.

make sure your browser support rendering markdown file
style the text like a code

Another way to write API document is to use OpenAPI standard. It is useful if the APIs are RESTfulAPI. One of the implementation is Swagger. Usually there is a library on every programming language which support the developer to write API documentation with code first approach. For example, I use swagger in my ASP.NET project.

Swagger page
reader can try to execute a request, just like a sandbox

2. Structure

There is no single source of rules to write API Specification document. However, we can learn from the existing well-written documents. I would like you to see the API Specification documents I love to read from StackExchange, BCA, and Tokopedia. As this article is written, each documents look like this.

StackExchange API Specification Document
StackExchange API Documentation
BCA API Documentation
Tokopedia Seller API Documentation

If you see the eagle view of those documents, each have common structure. I would write it shortly as below.

— Title
— Changelog or versioning
— Table of Contents
— Introduction
— Conventions
—Body

3. Changelog or Versioning

Use this section to describe all changes brought on the latest version. Write the date, version, and the description in simple yet clear sentences. Below are examples of Changelog.

StackExchange API Documentation Changelog
Tokopedia Seller API Documentation Changelog

4. Table of Contents

Use Google Docs or Microsoft Word-like table of contents, or make the headers available on the sidebar.

table of contents with page number
Sidebar table of contents

Introduction

This section should be short and simple, because the reader doesn’t have much time to walk through the paragraphs. Write few sentences at the beginning of document or every subsections to describe what is the context and what to expect when reading through it. Below are the examples I take from StackExchange and Tokopedia.

Stack Exchange API v2.3

This is the documentation for the v2.3 Stack Exchange API (with both authentication and write support). If you have additional questions, or believe you have encountered a bug, don’t hesitate to post a question on Stack Apps.

If your application is in a runnable state (even a beta one), Stack Apps is also the place to list it.

Tokopedia Seller API Documentation

This document contains the reference and guideline for Tokopedia Seller API Services. This API allows you to integrate your system into Tokopedia. You can manage products, orders, and shops using all API’s that we provided on this document. Tokopedia Seller API Services is a JSON-based OAuth2 API. All requests must be secure (https) and authenticated.

Conventions

This section is very important to bring the reader to the same page with us the writer. Below are the topics you may want to standardize for the upcoming contents.

— Protocol : REST/RPC/SOAP/etc
HTTP Status Codes
— Custom Status Codes : these codes, if exist, may vary in each companies
— Error message : Problem Detail
— Authentication : JWT/OAuth2/etc

Body

This section is very broad. Anything related to the context of the document can be written here. Make sure you don’t write something redundant or anything that can be written on the previous sections.

For the context of API Specification document, usually the Body is filled with HTTP method, endpoints, request-response format, examples, and diagrams. Here are the examples of contents from StackExchange, BCA, and Tokopedia.

StackExchange API documentation content
BCA API documentation content
Tokopedia API documentation content

I hope this article helps you to write better API Specification document. Please clap and share this article, maybe your audience can take advantages from my writings. See ya!

--

--

fariz mamad

Write about software engineering and career

Recommended from Medium

Lists

See more recommendations