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