How To Write Technical Documentation For REST/Web APIs

Why write API reference documentation? If your company develops APIs, then you can provide reference documentation for each API available with the product. The API documentation should describe the common components used by each of the APIs for iOS, Android, and other platforms.

Essentially, the API reference documentation explains the data structures available through the APIs. If well written, this will increase the usage and popularity of your APIs and encourage developers, testers, and integrators to use your API products. But what is an API?

api-documentation-template-ms-word

API Template - Download Here

What is an API?

An application programming interface (API) is an interface implemented by a software program to enable interaction with other software, much in the same way that a user interface facilitates interaction between humans and computers.

APIs are implemented by applications, libraries and operating systems to determine the vocabulary and calling conventions the programmer should employ to use their services. It may include specifications for routines, data structures, object classes and protocols used to communicate between the consumer and implementer of the API. Wikipedia

Concept

An API is an abstraction that defines and describes an interface for the interaction with a set of functions used by components of a software system. The software that provides the functions described by an API is said to be an implementation of the API.

An API can be:

  1. Generic — the full set of API that are bundled in the libraries of a programming language (e.g. the standard Template Library in C++ or the Java API)
  2. Specific — meant to address a specific problem, like the Google MAPs API or the Java API for XML Web Services.
  3. Language-dependent — available only in a given programming language. It is only available by using the syntax and elements of that language to make the API convenient to use in this context.
  4. Language-independent — written in a way that means it can be called from several programming languages. This is a desired feature for a service-oriented API that is not bound to a specific process or system and may be provided as remote procedure calls or web services.

For example, a website that allows users to review local restaurants is able to layer their reviews over maps taken from Google Maps, because Google Maps has an API that allows it. Google Maps’ API controls what information a third-party site can grab, and what can be done with it.

“API” may be used to refer to a complete interface, a single function, or even a set of multiple APIs provided by an organization. Thus, the scope of meaning is usually determined by the person or document that communicates the information.

API Documentation Benefits

  • Encourage platform adoption as developers will be able to modify the code faster
  • Reduces customer support costs as developers can find the answers they need
  • Allow programmers to focus on coding
  • Ensure software is documented in depth

API Documentation Structure

  • Overview – explain the advantages of using the APIs and include, if possible, diagrams
  • Getting started – explain how to get started, and other tutorials that help orient the reader, for example, setting you authentication and access tokens
  • Reference material – define the purpose of each resources, setting, and parameter in the code. Include default values and other information that helps the reader.
  • Sample Code – this is what’s of most interest to the developer. Include code samples that have lots of detailed comments so they can understand how each parameter works. Give default values and examples

Getting Started

Provide lots of code samples, from hello world applications to more complex examples. The key thing is to help them get started. Tutorials do this too. Walk them through simple use cases, then add more layers of complexity so they work their way into the API.

Sample Code Guidelines

Provide sample code that the developer can use to get started. Developers learn by doing – coding – not reading. So give them oodles of sample code to get started with.

Code samples should contains the following sections.

  • Overview – explain the purpose of this code sample. One sentence is usually enough.
  • Requirements – how to run the code sample
  • Demonstrates – what happens when you run the code
  • Sample Code – detailed code sample with comments

Create sample code using the following guidelines:

Comments

  • Provide comments for every method, parameter, or setting that needs explanation.
  • Use comments anywhere the code is not obvious, especially if you need to document a work-around or something unusual.
  • Comments can be several lines long if required.
  • Use complete sentences and don’t be afraid to be wordy.

Reference Material

Most API documentation is reference material. This is where you document the specific details for each resource, method, parameter as well as default values and exceptions.

Reference material, at a minimum, describe the following:

  • Purpose of the item, for example, request parameters
  • Default values
  • Return Values
  • Exceptions
  • Recommendations
  • Cross-references to other useful information
  • Code samples

How to Write API Documentation – Free eBook

Click here if you want to a 16-page How to Write API Document tutorial that 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.

api-documentation-template-ms-word

API Template - Download Here

Download these templates to start

Acceptance Test Plan

Contingency Plan

Software Development Templates

Acquisition Plan

Conversion Plan

Software Requirements Specification

Action Plan

Cost Benefit Analysis

Software Testing

API Documentation

Database Design

Standard Operating Procedures (SOP)

Audience Analysis

Datasheet

Statement of Work

Availability Plan

Deployment Plan

System Administration Guide

Bill of Materials

Design Document

System Boundary

Business Case

Disaster Recovery Plan

System Design Document

Business Continuity

Disposition Plan

System Specifications

Business Plan

Documentation Plan

Technical Writing Templates

Business Process

Employee Handbook

Test Plan

Business Requirements

Error Message Guide

Training Plan

Business Rules

Expression of Interest

Transition Plan

Capacity Plan

Fact Sheet

Troubleshooting Guide

Case Study

Feasibility Study

Use Case

Change Management Plan

Functional Requirements

User Guide

Communication Plan

Grant Proposal

Verification and Validation Plan

Concept of Operations

Implementation Plan

White Papers

Concept Proposal

Installation Plan

Work Instructions

Configuration Management Plan

Interface Control Document

Software Development Templates

Acceptance Test Plan

Maintenance Plan

Software Requirements Specification

Acquisition Plan

Market Research

Software Testing

Action Plan

Marketing Plan

Standard Operating Procedures (SOP)

API Documentation

Needs Statement

Statement of Work

Audience Analysis

Operations Guide

System Administration Guide

Availability Plan

Policy Manual

System Boundary

Bill of Materials

Project Plan

System Design Document

Business Case

Proposal Manager Templates

System Specifications

Business Continuity

Proposal Template

Technical Writing Templates

Business Plan

Quality Assurance Plan

Test Plan

Business Process

Release Notes

Training Plan

Business Requirements

Request for Proposal

Transition Plan

Business Rules

Risk Management Plan

Troubleshooting Guide

Capacity Plan

Scope of Work

Use Case

Case Study

Security Plan

User Guide

Change Management Plan

Service Level Agreement (SLA)

Verification and Validation Plan

Communication Plan

Setup Guide

White Papers

Concept of Operations

Social Media Policy

Work Instructions

Concept Proposal

Contingency Plan

 

Configuration Management Plan

Conversion Plan