APIful Blog We're obsessed with Web APIs

Documenting APIs

Oct 14, 2015 •

Why not get right down to business with one of the most riveting topics in
computer science: documentation. However, after reading this article you might
just be convinced that in the land of APIs, documentation is not only
incredibly important but can also be fun (ok, I might be pushing it)!

Documentation for an API is the specification for how consumers will
interact with the API. This is akin to the interface documentation that is
created for traditional software projects (anybody else have fond
memories of cscope?). Without documentation
it is essentially impossible to integrate with an API and is certainly not

There are numerous options available for documenting APIs, each with their own
pros and cons. There are three primary categories of tooling:
general purpose documentation tools, code documentation tools and
API specific tools.

General purpose documentation tools include things like wikis and online
collaborative document editors. The barrier to entry is zilch, which explains why these
are so common. They are not ideal in that they are unstructured and typically
lacking completeness. They are also not particularly friendly in terms of
presentation and navigation for outside consumers.

Code documentation tools have traditionally been used to document source code
with markup that is then turned into documentation. Examples include
RDOC or YARD for Ruby,
jsdoc for JavaScript or
for all things Java. The benefit of these tools lies in their ability to closely
couple the API documentation to the code that implements it. This helps with
the all too common problem of updating the code and forgetting to update the
documentation. As well, this approach can leverage existing infrastructure and
expertise to enable developers to document APIs without learning a new tool.
These benefits help to get things started but ultimately this approach leaves
much to be desired in terms of capturing semantic meaning for the API
definitions (i.e. a baseurl isn’t just an italics piece of text).

API documentation tools are a set of languages and supporting
tools that are designed specifically for APIs (typically RESTful APIs). The
heavy hitters include: Swagger, RAML,
I/O Docs and apiblueprint.
Digging into each of these toolchains reveal numerous benefits for those who
publish APIs. The key is the semantic markup language that each specification provides.
These yaml/json formatting schemas allow for API specific information to be
documented and arranged in representative hierarchies. This domain specific
language then enables for the development of a tooling ecosystem.
Most languages supply visual editors that aid in creating the respective formats as
well as tools that can render the specification as an interactive API explorer.
More advanced tools are available to automatically introduce API mocking services
or to output a scaffolding of the code that will ultimately implement or consume
the API. Exciting stuff!

Trade-offs remain in terms of the degree of coupling between the above options
and the actual source code implementing it. For example, Ruby on Rails provides
a very robust RESTful set of conventions – it would be great if the bulk of
the associated Swagger documentation would be automatically generated. Tools
exist to lessen the pain but the markup leaves source code looking busy with
far too much “non-source” information in the files. However, decoupling the the
documentation from the code completely results in double-documenting aspects of
an API that could be easily discovered (statically or dynamically) from the
development framework of choice. This is a topic to be revisited in the future.

As a community, the faster we can move to the third type of documentation, the
faster we can further advance the technologies surrounding API composition and
integration scenarios. If you or your organization has yet to take advantage of
the API documentation tools please set aside a Friday afternoon to
investigate and experiment. Our team recently experimented with an
“API driven design” approach for a project. We sat down, developed the REST
interfaces in Swagger first and then moved on to writing the backing code that
realized the specification. Thus far it has proven a success but certainly more
experience is required.

What do you think? Is there another option missing?

Curious what Watson Analytics thought of this post? Well here is the result from Watson tone analysis:

Share via a Tweet or follow us for everything APIs!