Need to write your first API document but don’t know where to start? This 16-page How to Write API Document tutorial explains how to write each section in your API reference documentation. It includes helpful explanatory text that walks you through the process of documenting each section in the API, including the parameters, endpoints, requests, responses, and endpoints. You can change everything in the document – text, images, and tables.

1. How to Write
API Documentation
Version X.x ● 06 November 2016
Company Name - Address - Telephone - Email - www.klariti.com

2. How to Write API Documentation V1.0
2 | P a g e
© Klariti Ltd
Preface
Intended Audience
The document is writer for technical writers, business analysts, and developers involved in
writing API reference documentation.
Style Conventions
The following style conventions are used in this document:
Bold
Names of commands, options, programs, processes, services, and utilities
Names of interface elements (such windows, dialog boxes, buttons, fields, and menus)
Interface elements the user selects, clicks, presses, or types
Italic
Publication titles referenced in text
Emphasis (for example a new term)
Variables
Courier
System output, such as an error message or script
URLs, complete paths, filenames, prompts, and syntax
Courier italic
Variables on command line
User input variables
< > Angle brackets enclose parameter or variable values supplied by the user
[ ] Square brackets enclose optional values
| Vertical bar indicates alternate selections - the bar means “or”
{ } Braces indicate content that you must specify (that is, x or y or z)

3. How to Write API Documentation V1.0
3 | P a g e
© Klariti Ltd
Table of Contents
1. Getting Started .......................................................................................................................... 4
1.1. What You Need to Document............................................................................................. 4
2. Terminology .............................................................................................................................. 6
2.1. API Terminology .................................................................................................................. 6
2.2. Endpoint Terminology......................................................................................................... 6
3. Understanding Resources ....................................................................................................... 8
4. Documenting Path Parameters in Endpoints ....................................................................... 9
5. Parameters ............................................................................................................................... 10
5.1. Parameter Column Order.................................................................................................. 10
6. Parameter Types ..................................................................................................................... 11
7. Data Types............................................................................................................................... 12
7.1. Parameter Order ................................................................................................................. 12
8. Sample Requests ..................................................................................................................... 13
8.1. Sample POST Request........................................................................................................ 14
8.2. Sample GET Request.......................................................................................................... 14
8.3. Sample Responses............................................................................................................... 14
8.4. HTTP Response Format..................................................................................................... 16

4. How to Write API Documentation V1.0
4 | P a g e
© Klariti Ltd
1. Getting Started
Before we start. There is no ‘right’ way to document an API, though there are many wrong
ways to do it.
In other words, it’s up to you, the API writer, to shape the documentation so that it helps
the reader, typically a developer, to understand how the API works.
But it needs to provide more than the ‘bare bones’ parameter settings. This is where the
value of code samples comes in. It’s by using the API that you truly understand it.
Your role when writing this document is to imagine you’re sitting right next to the
developer – one that has never seen your API before – and help them get started, play with
it, and enjoy using it.
So, how can you do this?
Stripe API documentation
1.1. What You Need to Document
This guide discusses how to write API documentation, in particular Web and RESTful
In principle, documenting any type of API is the same. However, due to the popularity of
Web and Rest APIs, we decided to focus on these in this tutorial.
Your REST API documentation needs to include, at a minimum, the following:
 Resource description
 Endpoint
 Methods

5. How to Write API Documentation V1.0
5 | P a g e
© Klariti Ltd
 Parameters
 Request example
 Response example
 Status and error codes
 Code samples

6. How to Write API Documentation V1.0
6 | P a g e
© Klariti Ltd
2. Terminology
One of the confusing things about APIs, is that the terminology tends to be used
interchangeably. Some prefer to use the term object, others resource, other methods and so
on. There are several reasons for this, some legitimate. For example, not all APIs are Web
or RESTful. This may sound obvious but it can lead to a little confusion.
2.1. API Terminology
As there is no one right way to document an API, the terminology used to describe a
resource varies.
The following terms are used interchangeable. As this tutorial is focussed on the RESTful
APIs, we’ll use resource when describing ‘things.’
 API calls
 API methods
 Calls
 Endpoints
 Objects
 Requests
 Resources
 Services
2.2. Endpoint Terminology
The term used to describe endpoints also varies. You might see some of the following used
in API documents:
 API methods
 Endpoints
 Requests
 Resource URLs
 URL syntax
 URLs
I use endpoint.
My suggestion is to choose one and stick with it. Personally, I prefer to use resources and
the endpoint to access that specific resource.

7. How to Write API Documentation V1.0
7 | P a g e
© Klariti Ltd
What is an end point?
An endpoint gives you access to a resource. It’s the URL path.
What’s a resource?
It’s the data the endpoints interacts with.
Here’s a JSON representation of a resource.
{
"ID": "1",
"Name": "Ivan Walsh",
"Email": “ivanwalsh@somegmail.com",
"Country": "Ireland"
}
XML representation of a resource.
<Person>
<ID>1</ID>
<Name>Ivan Walsh</Name>
<Email>ivanwalsh@someothermail.com</Email>
<Country>Ireland</Country>
</Person>

8. How to Write API Documentation V1.0
8 | P a g e
© Klariti Ltd
3. Understanding Resources
When documenting your REST API keep the following in mind:
 Each resource requires at least one URI.
 A RESTful service uses a directory hierarchy to address its resources.
 The URI identifies a resource or a collection of resources.
 HTTP verbs determine the operations.
 The URI should not describe the operation or action.
A resource car can be addressed like this:
http://MyThings/Car/1
This URL has following format:
Protocol://ServiceName/ResourceType/ResourceID
Recommendations for well-structured URIs:
 Use plural nouns for naming your resources.
 Use verbs for the names of operations.
 Write VERBS in all caps. POST, GET, DELETE etc.
 URIs are case insensitive. Use camel case or all lower-case URIs.
 Avoid verbs for your resource names.
 Avoid using spaces. Use an _ (underscore) or – (hyphen) instead.

9. How to Write API Documentation V1.0
9 | P a g e
© Klariti Ltd
4. Documenting Path Parameters in Endpoints
As always, write the document to help the reader find the information they need quickly.
Remember that as many readers will be scanning your API document on mobile devices,
make the most important piece of information stand out.
When documenting path parameters in your endpoint, use curly braces {} and, if possible,
color coding. That way it’s hard to miss.
It’s common practice to represent path parameters in your endpoint using curly braces {}.
For example:
/photo/{user_id}/send

10. How to Write API Documentation V1.0
10 | P a g e
© Klariti Ltd
5. Parameters
Without parameters, the API doesn’t go anywhere. In short, we use parameters to
configure an endpoint, that is, so you can do something with the API.
In general, parameters are displayed in a table making it easy for the reader to scan your
API reference document.
At minimum, you need to document the following:
Method Purpose
Parameter Identify the parameter. Note if it is case sensitive.
Type Identify the type: string, integer, object, Boolean etc.
Description Describe what it does in a single sentence. Be precise. Remove noise.
Highlight any default or recommended settings.
Required Is it mandatory? If so, write Yes. Otherwise leave blank.
Examples Provide simple examples to help the reader grasp the purpose of the
parameter. The Twitter API includes many examples to help you, the
developer, to implement that API. I think is a nice way to help the developer
get up to speed faster.
5.1. Parameter Column Order
After looking at many API Reference websites, the table above seems the most practical
way to illustrate the parameter settings. Saying that, some API sites prefer to put the
Required field in the second column to stress that it’s mandatory, that is, it must be
included in the call.
Finally, the term Required is often written as Required? or Mandatory. The important
thing is to choose one and be consistent across your documents.

11. How to Write API Documentation V1.0
11 | P a g e
© Klariti Ltd
6. Parameter Types
This bring us on to the different types of parameters.
REST APIs have four parameter types. If you’re documenting other type of parameters,
you may need to include others. Just keep that in mind. For now, you need to be aware of
the following:
Parameter Type Location
Path Path of the endpoint, before the query string (?)
Query string Query string of the endpoint, after the ?.
Request body Request body. Usually submitted as JSON.
Header Request header. Usually relates to authorization.

12. How to Write API Documentation V1.0
12 | P a g e
© Klariti Ltd
7. Data Types
As mentioned above, the following data types apply to RESTful APIs. If you’re
documenting other APIs, such as Java, please make sure you’ve covered your bases.
For now, we need to identify the data type for each parameter. To do this, make sure you
document the following data types as these are the most common:
Data Type Definition
String Alphanumeric sequence of letters and possibly numbers.
Integer Whole number — can be positive or negative.
Boolean True or False.
Object Key-value pairs in JSON format
7.1. Parameter Order
This is a small detail but worth mentioning.
The order in which you pass parameters doesn’t matter.
What I mean is that if you have three parameters — time, date, and location — you can put
these in any order in the query string and get the same result.
To add parameters with a query string (?) at the end of the endpoint, use ampersand (&) to
separate them.
For example:
/myresource/{userId}?time=0945&date=12212018&location=dublin
and
/myresource/{userId}?location=Dublin&time=0945&date=12212018&
return the same result.

13. How to Write API Documentation V1.0
13 | P a g e
© Klariti Ltd
8. Sample Requests
So, give me some examples?
This is what the developer wants to know when reading your API Reference
documentation.
Example of Request and Response.
Examples put everything in context. Actually, from one angle the examples are more
valuable than the text descriptions. Why? The developer can use the code sample to as a
starting point and see how it actually works. Of course, you as a technical writer, need to
understand the parameters to create great code samples. I recommend Postman to create
samples
The sample request clarifies how to use the endpoint

14. How to Write API Documentation V1.0
14 | P a g e
© Klariti Ltd
Although you’ve already listed the endpoint and parameters, you should also include one
or more sample requests that shows the endpoint integrated with parameters in an easy-to-
understand way.
8.1. Sample POST Request
Here are example of sample request.
PayPal sample POST request
8.2. Sample GET Request
PayPal sample GET request
8.3. Sample Responses
It’s important to provide a sample response from the endpoint.
 Include important header information. Otherwise, leave it out.
 Define the values in the endpoint response

15. How to Write API Documentation V1.0
15 | P a g e
© Klariti Ltd
 Describe items in the response if necessary.
 Describe the labels in the response if they are abbreviated or non-intuitive.
 Use realistic values in the response
Sample Response

16. How to Write API Documentation V1.0
16 | P a g e
© Klariti Ltd
8.4. HTTP Response Format
The server returns <response code>, which contains the status of the request. This response
code is generally the 3-digit HTTP status code.
These diagrams shows the format of an HTTP requests and responses:
HTTP Request Format
HTTP Response Format
<Response Header> contains the metadata and settings about the response message.
<Response Body> contains the representation if the request was successful.

17. How to Write API Documentation V1.0
17 | P a g e
© Klariti Ltd
Take the next step.
LET US SHOW YOU HOW TO
DEVELOP YOUR WRITING CAREER
We’ve put together the most effective training materials Klariti has ever produced...
The ebook you’ve just read has covered the very basics of writing great documentation...
but that’s only the beginning.
We’ve been building software and training material known since 1997.
Klariti opens to new members periodically throughout the year.
Interested?
Visit Klariti.com now to find out more.