In the first part of this article, I explain what an API is and how it works. I also mention the recipients of API documentation and the stages of its writing. This time, I want to focus more on the structure of API documentation and explain its elements one by one. So let’s get to it! Be prepared for a ton of technical knowledge 🙂
API documentation should be divided into two main parts: conceptual material and reference material. It is important that they are clearly separated, for example, in different chapters or sections within a chapter.
Most frequently documentation is in English as it is the most common language of programmers, for whom the documentation is aimed.
Let me start by explaining what conceptual material usually contains. It provides a user with reasons to use a particular API and business benefits that it brings. It also includes the following information:
- A glossary of terms explaining the main concepts specific to a given API.
- A diagram showing the various processes of an API, with an explanation of its architecture, the sequence of steps required to perform the most common tasks, and the data model with a brief explanation of what data is provided during API queries.
- A description of the requirements to set up the environment (both production and test), register, or obtain a special key or ID to connect to an API in a proper and secure manner.
This section should also guide a user to connect to a given API, which includes steps, such as registering, getting an API key and storing it, as well as the process of authenticating to send their first query. This guidance should be gradual, starting with simple tasks to more complicated ones. It’s also a good idea to attach relevant screenshots of the system to help a user go through all these steps.
This part of documentation is more extensive, as it lists all possible queries that can be made to a particular endpoint in a given API. It must be well organized and clearly written so that developers can use it effectively. In this section, each endpoint should contain the following information:
1. URL endpoint
You provide a URL (Uniform Resource Locator), which is a kind of an address in the form of a link to a resource, together with a brief description of what you can do with this resource when you make a specific query.
2. HTTP method
HTTP (HyperText Transfer Protocol) method describes an action performed in a given request to a specific resource when communicating with a given API. There are the following HTTP methods:
- GET – to retrieve a resource or a group of resources from a server,
- POST – to add a new resource to a server,
- PUT – to update an existing resource on a server,
- PATCH – to update an existing resource on the server, but the update concerns only a specific piece of information, and not the entire resource,
- DELETE – to remove a resource from a server.
It is worth mentioning that although the majority of APIs is HTTP-based nowadays, other protocols and integration methods are also employed (for example, RPC, TCP/IP, SMTP, and more).
3. Parameters
Parameters are additional information that you can include in a request to a given endpoint in order to influence the response from a server. There are the following types of parameters:
- Header parameters – often contain additional information, such as an authentication token or the format of the information sent.
- Path parameters – are added inside the URL of a given endpoint to identify a specific resource on which you want to take an action, such as editing or deleting a resource; such a parameter is separated by a slash (“/”) from the base URL path and written in curly brackets, for example, /cats/{id}.
- Query parameters – are also added inside the URL of a given endpoint, however, their use is mainly related to options for filtering, searching, or paginating information in a given resource; such a parameter is separated by a question mark (“?”) from the primary URL path, for example, /cats?breed=bengal.
- Body parameter – contains information required for a server to process a query correctly; this parameter is obligatory when creating a new resource or updating a currently existing one.
4. Data type description
Such a description contains details about the types of data included in the information sent or received. There are the following data types:
- Number – presented as an integer or decimal number (note that a decimal number in programming is expressed by a period, not a comma).
- String – is a text data type used to store a string of characters written in double or single quotation marks; it can contain letters, digits, punctuation marks, or spaces, for example, “8 Woloska Street, Warsaw” or “4522-3757-3419”.
- Boolean – is a so-called logical operator; it can have two values: true or false.
- Null – indicates that there is no information in the database; it can also mean an unknown value; it is written without any quotation marks.
- Array – is a list of data values separated by a comma written inside square brackets; it can contain numeric values, a string of characters, or a mix of both, for example, [5, 2, 60, 7, 1, 6.5, 0], [“kot”, “pies”, “żaba”, “koń“], [45, “kot”, true, 21, null, 100].
- Object – is a combination of a group of data, often of different types; written in curly brackets, for example, {“pink”: 103, “yellow”: 555, “orange”: 34}.
5. Example of creating a query
Such an example should show how to create a query in a given programming language (or in multiple languages, if possible).
6. Possible responses and their formats
JSON and XML are the most common data formats; however, JSON is more popular and is now gradually superseding XML.
Below, you can find a sample description of an endpoint from the documentation of Twilio SendGrid – a company that provides a cloud-based email marketing tool.
Source: Create a transactional template. | Twilio (sendgrid.com)
In addition to describing all types of queries in a given API, you should include a description of any errors with status codes that a user can expect when communicating with an API.
Source: Stripe API Reference – Errors
It is worth emphasizing that there is no single, fixed way to describe an API. All the above is only a suggestion. Regardless of the choices made (such as a way to describe API endpoints), it is important to remain consistent throughout the documentation.
If API documentation is written using documentation tools, code snippets are often automatically generated. This makes work very easy, even if it is only when updating a code.
API documentation is often prepared in the form of a web page or as a downloadable package of HTML documents. Interestingly, some API documentation is also interactive and allows its user to directly test an endpoint.
If you wish to dig more into the topic of writing API documentation, I recommend a comprehensive tutorial: Documenting APIs: A guide for technical writers and engineers by Tom Johnson, who is the author of I’d Rather Be Writing – a website about the process of writing documentation and popular trends in the technical writing world.
Bibliography:
- International Technical Communication Qualifications Foundation (June 17, 2020). Syllabus – Technical Communication Professional Foundation Level [a PDF file]. https://itcqf.org/wp-content/uploads/2020/06/ITCQF_Syllabus_v2_0Jun2020.pdf
- Johnson, Tom (December 28, 2021). Documenting APIs: A guide for technical writers and engineers [a blog article]. https://idratherbewriting.com/learnapidoc/
- Tree Web Solutions (December 8, 2021). Fundamentals of REST API [a blog article]. https://treewebsolutions.com/articles/fundamentals-of-rest-api-68
Author
- Technical Writer•Business Analysis & Technical Writing
-
She is a Certified Technical Writer with two years of professional experience. She has been involved in writing user guides, release notes, and API documentation for customers in the Life Sciences sector. In her spare time, she enjoys hiking, climbing via ferratas, and evenings with a good book.
