How well are your API's documented?

So the latest Postman State of the API report has landed today.

The finding that really made my eyes pop was this:-

“In fact, less than 5% of individuals give the APIs they work with a 9 out of 10 or higher when rating how well documented these APIs are.”

Pretty incredible huh? I’m curious as to the state of your API documentation, and given such a low percentage what can be done about driving change here (or, if API’s are doing so well without documentation, does this prove a case for not needing it to be super robust?)

Give me your thoughts!


1 Like

I didn’t look through the study, but that high level bullet summary on the first page doesn’t make it clear if respondents were answering about internal or external APIs? For internal APIs, I think the standards of documentation are much lower for many companies. I think many people also feel like for internal APIs, they’re well designed/simple enough that they’re self evident, or that as developers are consumers, folks can refer to the code if necessary. I think we see similar with internal test frameworks - folks generally don’t document it, but then start wondering why there’s not good adoption/the automated tests don’t use the features of the framework/etc.

My current company has customer facing APIs, and we’re only now (year 7) getting around to worrying about dev experience. Previously, we relied heavily on auto-generated Swagger docs and lots of hand-holding during the tech-integration process, as well as a lot of institutional knowledge and random Word documents, sample requests, etc that got shared. Definitely a mess, and we’re trying to get more mature about this, relying less upon individuals in tech integration and trying to rely more upon well written documentation that tries to address workflows and other shortcomings that Swagger based documentation doesn’t provide.

1 Like

Our team has accumulated a decent amount of documentation debt on our web api framework, we have some high level documentation and swagger page, but it can be a decent learning curve now we are getting new highers that could easily not be so hard if documentation is better

this month we are taking steps to get rid of this documentation debt and ensure for future we dont accumulate any, we are doing this as follows:

  1. have technical documentation, we “micro service”-ish arcitecture, live within developers repos, via use of markdown or rst files (that will be render to html page via sphinx,
  2. we have qatesting repo, and within there also including high level more holistic documentation on platform that qa/ba/devs all help maintain (written in rst files rendered via sphinx)
  3. we recommend all devs/ba/qa to link and update documentation to tickets they finishing/verifying
  4. the hard requirement is on the release there must be verification that documentation has been updated

the idea of strategy is

  1. documentation is deployed with platform and is part of the release cycle
  2. it is easy to append small changes instead of doing large changes.
  3. having documentation be responsibility of all team spreads work out that shouldnt be large burden on any one person (no one likes to do it, just necessary evil)
  4. integrates documentation in location where code is being changed. lessen the points of contact and easy to remember
  5. allows to version documentation

What type of API is utilized?

  • internal to the team, internal to the company, external to the team, external to the company;
  • do you offer to others an API, or do you consume an API?
  • how profitable is it to document the API? time taken to document the API is time where developers and also possibly BA/Other engineers are not coding or working;
  • what is the documentation for? technical architecture, review from business, selling, offer to clients;
  • what type of documentation are we talking about? business, technical, code?
  • what type of format? diagrams, auto-generated, listing of capabilities, WSDL;
  • how many consumers the API has - 1/many?
  • how complicated is the API to understand/use?
  • is the API documentation a proxy question for other problems?
  • how often will the API be changed?
  • even if someone writes documentation - that can be almost irrelevant: not used, not understood, inappropriate, incorrect.
  • is the documentation to be written from the perspective of what you think an API does, or what it actually does? Should the documentation statements be tested?
  • who writes and maintains it? Do their managers agree to this task and allow them to spend the time there?
  • level of documentation: document that the API exists, document the location, how to reach it, call it, parameters, headers used, or go in detail and do field by field; logic, history, reasoning, link to business decisions, errors, etc…

I don’t understand how the questions and answers can be clear and straightforward.

From my experience:

  • I’ve worked with products with no documentation; It was fine for me. But in some cases awful for other testers or developers who didn’t care about questioning it, or the devs that wrote it, or even try to learn it, and would only start their work if a document/specification was given.
  • I’ve worked with products with up to date documentation; I learned to distrust it as it wasn’t necessarily true; Too many people were guided by it and believed it true - so plenty of bugs and problems were introduced;
  • I’ve worked with products with only basic documentation: endpoint, configuration, parameters names - just enough data to be able to import or call this API; It was enough in most cases as the API wasn’t going to change often, it didn’t cause problems in the 5 scenarios it was going to be used;

Our API documentation is exactly this. And honestly, it doesn’t need to be any more (or any less). In my opinion, API external documentation needs to have just enough information to call, use and test it, without it becoming cumbersome to maintain.