how to write rest/web api documentation ebook

How to Write API Documentation Version X.x ● 06 November 2016

Company Name - Address - Telephone - Email - www.klariti.com

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 | 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 | 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 | P a g e

© Klariti Ltd

Parameters

Request example

Response example

Status and error codes

Code samples


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 | 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": “[email protected]",

"Country": "Ireland"

}

XML representation of a resource.

<Person>

<ID>1</ID>

<Name>Ivan Walsh</Name>

<Email>[email protected]</Email>

<Country>Ireland</Country>

</Person>


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 | 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 | 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 | 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 | 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 | 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 | 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 | 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 | 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 | 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.

http://klariti.com/

http://klariti.com/

how to write rest/web api documentation ebook

Software