API Documentation

Documentation is most beneficial when accessible, consistent, stays up to date, and validated as part of the delivery cycle. Documentation allows for ease of use and alignment with API consumers and self-service users.

A lack of documentation is like navigating without a map – it leads to uninformed decisions that send you in the wrong direction. In terms of API quality, documentation should be non-negotiable for all teams. This section explores why its use by organizations is so critical to success in the API lifecycle.

Download the year on year trend report

Process

Documentation is a Priority to Most Organizations

0%5%10%15%20%25%30%35%I am not sureNo and documentation is not a priorityNo but we plan to in the futureYes but documentation is not a priorityYes and documentation is a top priority6%7%20%28%39%

This year, a substantial proportion of organizations reported that they do have API documentation in place – or, in the small case they do not (20%), they have intentions to do so in the future.

We see that the value of API documentation is universally recognized across all organizations – especially those with more than 10,001 employees while smaller organizations (500 or less employees) have documentation in place but don’t have it as high a priority as their larger counterparts.

Obstacles

Limited Time Due to Workload Remains the Biggest Obstacle to Keeping API Documentation Up to Date

0%5%10%15%20%25%30%35%40%45%50%55%60%OtherLack of budgetLack of tools or technologiesLack of personnelDocumentation is out of syncLimited time due to workload3%16%27%28%47%62%

We have found that according to 62% of survey participants, the biggest obstacle to providing up-to-date API documentation is “Limited Time”. Upon further analysis, we found that the documentation process of mid-size and large organizations was mostly impacted by “Limited Time Due to Workload”. These same cohorts – 101-500 and 1,001 or more employees – also conveyed the impact of documentation being out of sync as a key obstacle. “Lack of Budget” was the lowest impact but evenly felt across the entire survey group.

Important Features

Most Organizations Who Have External APIs Expose Them Through API Gateways

API GatewayWe do not expose public APIsAPI Management ToolAPI Developer PortalHosted Documentation30%20%18%15%15%API GatewayWe do not expose public APIsAPI Management ToolAPI Developer PortalHosted DocumentationOther

When it comes to exposing public APIs, we wanted to know which developer API portal, management and gateway tools were used by respondents. The results showed that 80% of survey participants expose third party APIs with the most common way to do so using an “API Gateway” (slightly less than one third) followed by “API Management Tools” (about one fifth).

Show Me How it's Done....Examples are The Most Important Aspect of API Documentation

ExamplesStatus and ErrorsAuthenticationParametersHTTP RequestsError MessagesMethodsCode samplesGetting Started GuideTutorialsSandbox EnvironmentResourcesSDKsChange LogsFAQsRate limiting and thresholdsGlossary0%5%10%15%20%25%30%35%40%45%50%55%60%65%66%59%55%50%49%41%34%32%25%24%21%18%13%13%9%8%6%

For this question, we asked participants to select the top five most important aspects of documentation. Respondents expressed their favoritism for “Examples in API Documentation” (66%) followed by “Status and Errors” (59%), “Authentication” (55%), “Parameters” (50%) and “HTTP Requests” (49%) rounding out the top five.

Segmenting by role, we found the most popular role of survey respondents, QA Engineers/Automation Engineers, placed the top importance, evenly, on four specific aspects of documentation: “Examples”, “HTTP Requests”, “Parameters” and “Status and Errors”.

Documentation Quality

One Third of Survey Participants Feel Their Documentation Needs Improvement

0%5%10%15%20%25%30%PoorVery GoodGoodAverageNeeds Improvement7%9%25%26%33%

Most organizations (51%) feel positive about their documentation having rated it from “Good” to “Average”; a select few (9%) felt their API documentation was “Very Good” while 33% of indicated their documentation was “Poor” or “Needs Improvements”.

Earlier we identified obstacles to having up-to-date documentation was “Limited Time Due to Workload”. These findings combined convey obvious areas to improve.

Methodology

OpenAPI Specification is Used by Over One Third of Survey Respondents

We use an API definition Developers document APIs We don't have a processWe have technical writersOther0%5%10%15%20%25%30%35%36%26%18%18%2%

When it comes to managing documentation, the most common means to do so is by using an API definition like “OpenAPI to Automate API Document Creation” (36%) followed by “Manual Code Annotations Created by Developers” (26%). Almost one fifth of survey respondents told us they “Don’t Have an API Documentation Process in Place”; we hope to see improvement in years to come!

Your Single Source of Truth

The SwaggerHub Integration For Confluence is Favored For Consumer Documentation

0%5%10%15%20%25%30%35% Bump.sh Drupal Other Redoc/Redocly HTML2 pages (SwaggerHub generated) No solution for API documentation Homegrown documentation system API Management/Gateway Vendor solution ReadMe SwaggerHub Integration for Confluence5%6%8%8%17%19%22%23%26%36%

Survey respondents were asked to select all the tools / ways they use to provide consumer-facing documentation.

The “SwaggerHub Integration for Confluence”, released only six months prior to this survey launching, gained a lot of interest and comes out on top as the most favored tool (36%). “ReadMe” came in as the second most favored tool at 26%. Almost one fifth of respondents shared that they do not have a solution for consumer documentation.

We hope that, like the cohort of respondents that shared they generally don’t have documentation (prior question), they are thinking about implementing it.