Give Your APIs A Personality With Live Documentation

good API  is often accompanied by bad documentation which makes adoption confusing and slow.  In this article I will discuss how to produce great documentation for your APIs.

This article is part of the  ‘Essentials’ series and focuses on the ground-level understanding required to undertake the journey in to the world of APIs and will through the course of the series build upon your skills and introduce you to core concepts.  This series is intended for people who wish to gain a rudimentary understanding of APIs such as students, new software developers and managers wishing to gain understanding and experience within their team.

It is astonishing to think about what happens in corporate software development divisions.  If there is any adherence to a life cycle I can only imagine the amount of planning, meetings, scrums and sprints as well as the endless cycles of tests required to produce a quality API.  Yet when released and made available for use the API is quite often supported by confusing, unclear and lackluster documentation.

Software developers and integrators need to understand your API.  The worse the documentation the more you rob your partners and developer community of essential knowledge and understanding with which to appreciate your API.

In this article I will base the task of producing quality documentation upon two competing standards.  Whilst there are others available I have selected and used these standards for their abilities to provide an easy system with which to produce and render the documentation as well as their abilities to support multiple programming languages.

Selecting A Documentation Platform

Good documentation not only supports an API but enhances it.  Therefore careful consideration must be given to the selection of suitable documentation platforms so that it effectively supports and increases the use and adoption of APIs.  Below are some useful pointers to consider when selecting a documentation platform.

Market Prominence

Although as both a solutions architect and integration blogger I am always on the lookout for the next best thing but in a corporate environment sensibility must prevail.  Ideally the solution I would choose and recommend is one that has market traction behind it, should it fit the requirements.  In a commercial sense one would desire the solution to be actively developed and actively supported with a good track record of implementation and usage across other organizations.  In an open-source environment I would look for a solution that has a very active developer community which could be monitored via sources such as Github or support forums.

Industry Backing

From time to time vendors push for new standards, marketing phrases or terminology and it is always interesting to see these initiatives fade in to darkness at the lack of enthusiasm from the industry.  Thus one of the core criteria I base my decisions upon is whether or not a significant portion of the industry is on-board with the vendor’s initiatives.  Open-source communities are prime amongst those developing and pushing for new standards which I view with skepticism until supported by prominent industry names.

Writing Specifications

Producing live documentation requires that the API specifications be written in a form of mark-down/mark-up/parameterized language that is readable by both human and machine.  Being a descriptive language it contains form, syntax and grammar in the form of parameters.  Different platforms distinguish themselves by how easy the language is to adopt and use.  This is rather subjective as I prefer one that is more on the higher end and being more difficult but more powerful, but this is suited to my skill and confidence levels.  Ultimately there should be recognition that a certain level of up-skilling would be required.

Editing Tool

For me this is an area of higher weight than some of the other criteria listed herein.  The editing tool is the predominant interface that will be used frequently throughout the process and a poor tool will contribute greatly to poor documentation.  Personally unless a tool includes a feature that must, for specific and sound reasoning, be run on a local machine I generally prefer the use of on-line and cloud-based tools for the convenience and benefits provided by such.  That being said I use a number of different documentation systems both cloud-based and desktop-based.

Rendering Interface

Because the API specifications are written in an intermediate format it requires the assistance of a rendering engine in order to produce the final output.  This engine usually sets the platforms apart.  I prefer one that clearly and logically separates the API’s endpoints and allows for clear and descriptive layout of the essential inner mechanics of the API.

API Builder

The most recent and more powerful platforms, some which are open-source, have introduced mechanisms by which one can produce stub client or server implementations of the API.  Whilst some may prefer a particular framework these mechanisms do allow a person to easily generate client (consumer) applications which can be used as a basis for integration in to other frameworks (such as WordPress plugins) or even as a basis for unit tests.

Language Support

Today APIs are universally supported by many languages and a core differentiator is how well each of the platforms supports a desired language.  The good news is unless you are writing in some obscure language known only to a community of 5 developers or are programming in a language before 1977 you’re covered.

Based on the requirements above I generally use Swagger and API blueprint as my most prominent documentation frameworks.  However for the purposes of this ‘Essentials’ article and to get our feet wet in the concept of live documentation I’ll be focussing on the most prominent standard being Swagger.

Up Next: What Is Live Documentation?

Pages: 1 2 3

Written by YourAPIExpert