6 things to prepare when writing API Specification Document
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!
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!
Table of Contents
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.
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.
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.
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.
4. Table of Contents
Use Google Docs or Microsoft Word-like table of contents, or make the headers available on the sidebar.
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.
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!
