The Art of API Documentation: Part 1.
The conceptual framework for API documentation.
This article explains the conceptual framework and understanding of an API, the structure of API documentation, and why API documentation is very important.
What is an API?
API stands for an application programming interface. It defines how two pieces of software communicate with each other. APIs enable developers to reuse existing software solutions that reside in a third-party database by integrating functionality from existing platforms thereby reducing repetitive development. The well-known APIs are Twitter API, Open Weather API, Google location API, and GitHub API.
According to BusinessWire, a Berkshire Hathaway company and a leading-edge healthcare technology company, “API is a call and response process”. It’s a software program that enables others to ask for data and submit requests to make use of third-party data.
Why is good API documentation necessary?
API documentation provides developers with instructions on using API services, including code examples, tutorials, and details on functions, classes, and return types, enabling integrations and API calls.
When you write API documentation, you tell the software developer and audience to use the API for their web app integration. Good-quality API documentation increases developers' adoption, thereby decreasing support costs by allowing developers to have access to a third-party interface where they can integrate and extract information. API documentation explains endpoints, usages, and provides specific examples.
To understand the growth in APIs over the years, and how important APIs are, MarketSplash survey among developers shows that most developers incorporate APIs, with 69% using third-party and 20% using internal or private ones. Also, states that open banking API calls are expected to grow from 102 billion in 2023 to 580 billion in 2027.
With the release of a library of over 4,800 application programming interfaces (APIs) by Berkshire Hathaway for its VBASoftware platform, VBA clients and customers have access to a library of APIs, which gives them the freedom to manage their data without having to build a separate database.
The two most common types of APIs
Web APIs (REST, SOAP, etc.)
Platform APIs (Java, C++, etc)
APIs are written for specific programming languages.
To understand the basics of how APIs work look at tools like
{JSON} which stands for JavaScript Object Notation,
<XML> stands for Extensible Markup Language
REST API stands for Representational State Transfer
Conceptual Material Framework in API Documentation
The conceptual material framework is more like classic technical writing that contains a high level of information to get the developers oriented and started with the API. This is valuable for teaching developers how to write code that performs a common task by using an existing concept to solve a particular problem.
Why is conceptual material documentation important?
The conceptual material API documentation helps developers read and understand why they should use a certain API framework or guideline. This communicates to them how easily they can get started; otherwise, they will give up. When API material is not well documented, it is often difficult to figure out how to do common tasks by just looking at the material.
Writers are very important for very good and quality API documentation. Often, developers aren’t great at reference material documentation and tend to be bad at conceptual material. They focus more on ‘how’ to use this API and forget ‘why.’ Longer paragraphs tend to be challenging for developers to read.
Structure of API Documentation
Overview Material
Getting Started
Tutorials
Sample Code
Tools for REST APIs
Hands-on Exercise Tools
A sample structure of GitHub REST API documentation. Mindful to know that there are no rules for the structure of API documentation but certain structures are basics for easy understanding of the API docs.
Overview Material
The overview documentation section is very important, as it is always the first insight that communicates what the API can do. What is required in using the API, and how it is designed? It tells developers or users why they should use the API, with lists of requirements and a good description of key features and use cases.
This section helps developers or users of the API quickly figure out if this API solves the problem that they want to solve.
For example, If you want APIs that store data in the cloud, you could start talking about creating payment features or insurance data that could store data in the cloud and integrate with your API.
This section should include API requirements, including authentication servers and programming languages, for developers to understand what the API supports. More so, the operating systems, SDKs, IDEs, etc. with version numbers that are required or supported.
Key concepts: The description of the API key concept is essential as it is a guide to communicate the area of domain names that are possible.
An example explaining the key concepts is the online banking system: accounts, transactions, etc.
Getting Started Session
The getting started section of API documentation is mostly the intriguing part, which could be intimidating for developers when the language is not clear enough and hard to understand. This section should lead users through the first simple tasks and processes to demonstrate some simple features of the API.
This should consist of step-by-step instructions with screenshots and as many sample codes as possible. More often, avoid longer tests as they could be boring and instead stick to short paragraphs that are direct and concise. The idea is to make it easy to understand the API implementation.
Web API: Getting Started Section could include;
Web API registration.
Getting the API key, authentication, and authorization
Making simple HTTP requests that return a response and sample codes
Platform API: Getting Started could include;
Downloading the SDK
Setting up your IDE
Creating an app that does a simple task
Source code or sample codes
Show pictures of different APIs
Tutorials
The tutorial section should contain common tasks and sample codes that developers could copy and modify to easily work on. The tutorial section is not much different from the Getting Started section as it contains step-by-step instructions and could include screenshots and a simple program to practice.
It is good to differentiate sample codes from production codes. The complexity of the API tends to determine how long the tutorial can be. For most documentation, 4 to 6 tutorials are sufficient, but complex APIs could have more tutorials.
Sample Code
The illustration of concepts through sample code is very important as it covers guidelines for choosing languages, different API forms, illustrations of workflows, meaningful names, object-oriented programming, and comments.
Sample Code Guidelines
The sample code guidelines prioritize the language in which the APIs can be written and show clarity of information. Developers want sample code that is easy to understand and their workflows, as it is one of their priorities when reading API documents. However, it is worth noting that the sample code is not the same as the production code.
Many developers learn by example, as it is the easiest way and faster than writing the code from scratch. The Web API sample code is always very simple, but we cannot say the same for the Platform SDKs, whose sample code could be simple and complex at the same time depending on the SDK.
For example, Web API sample code illustrates a result from one HTTP call that is used for parameters in a second HTTP call. Take a look at GitHub API.
For the Platform API, the API calls initialize the SDK, followed by calls to take action, and finally a call to shut down the SDK.
Looking at a few API docs like the Stripe API Stripe.com and the Open Weather API. For both production and sample code, variable, class, and member names should be clear. The use of meaningless names should be avoided, as should names that could raise biases or concerns among users.
Workflows:
The illustration of workflows shows what your API does and how the sample code could demonstrate common tasks. The order of steps taken to do common tasks The workflow typically explains how to complete a task, especially when making API calls. The workflow describes the order of these tasks. For example, the workflow for a song from a playlist can be like this:
Get a list of all playlists and their IDs.
Let the user select a playlist.
Get the list of songs and their IDs and specify using their playlist ID
Let the user select a song.
Request the sound file using the song ID.
Architecture diagrams and/or data models: This gives a general view of the information with graphics. The exposition of the diagram is very useful and is sometimes not shown by many APIs. The architect diagram shows how the various pieces fit together, and the workflow diagram shows what happens when the API call is made.
The next article Art of API Documentation Part 2 will treat topics on JSON, XML, and REST API tools. Don't miss to read it to understand how these various tools enable the performance of API calls and responses.
To understand and read more about API, the Rapid API blog explains in detail the various types of APIs.