2020 State of the API Report
Executing on APIs
API performance and change
While APIs appear to be perceived as stable and reliable, angst may be rising for when APIs break or change. A significantly higher number of respondents than last year said APIs don’t break, stop working, or materially change specification often enough to matter, which was the top response; however, the percentage of respondents who feel APIs still break too frequently also rose significantly versus last year.
Within primary job functions, support engineer was most likely to report that APIs break not enough to matter. Within industries, nonprofits and manufacturing were most likely to report that APIs break not enough to matter. Within functional areas, technical customer support and security were most likely to report that APIs break not enough to matter.
API-first leaders were less likely to report that APIs break too frequently, while respondents with 6+ years of API development experience were more likely to report they break too frequently than those with 0–5 years of experience.
How frequently do APIs break, stop working, or change specification?
Obstacles to producing APIs
When asked about the obstacles to producing APIs, lack of time is by far the leading obstacle, with 52.3% of respondents listing it. Lack of knowledge (36.4%) and people (35.1%) were the next highest.
Looking at the top three mentions, API-first leaders were more likely to mention lack of time, lack of knowledge, and lack of people than others. Respondents with 6+ years of API development experience were less likely to mention lack of time, lack of knowledge, and lack of people than those with 0–5 years of experience.
Obstacles to consuming APIs
When asked about the biggest obstacle to consuming APIs, lack of documentation clocked in the highest obstacle to consuming APIs (54.3%), by an extremely wide margin. Other top obstacles to consuming APIs are lack of knowledge, complexity, and lack of time, all cited by a little over one-third of respondents.
Respondents with 6+ years of API development experience were more likely to mention lack of documentation than those with 0–5 years of experience.
Collaborating on APIs
When asked how they collaborate, respondents leaned toward sharing URLs to API artifacts (Swagger, OpenAPI, etc.) which received the highest percentage of mentions at 43.2%. This was followed by publishing those artifacts to GitLab, GitHub, Bitbucket, etc. at 40%. Publishing API documentation to an API portal logged in third-highest at 39.2%.
Instant messaging applications may be ideal for quick communication, but only ranked as the fifth-highest collaboration tool at 28%.
When it comes to preferred change-management practices, the utilization of Git repositories scored the most mentions, at 62.9%. Logging in succession behind that top response we find versioning APIs (59%), versioning server code (34.6%), and versioning client code (27.8%). Applying semantic versioning lagged behind at 20.9%.
API-first leaders and respondents with 6+ years of API development experience were more likely to mention each of the top two mentions (i.e., Git repositories and versioning APIs).
When it comes to API testing, a wide variety of practices are applied, although functional testing (70.4%) and integration testing (67.1%) towered over the rest. Performance testing (48.4%) and acceptance testing (42.8%) trailed behind, followed by security testing at 35.8%.
We asked how well APIs are documented, and the results resembled a bell curve, with the highest percentage of respondents (27.7%) indicating that documentation scored a 5 out of 10 (or "OK"). The average score on the 10-point scale was just over 5 (5.06). Only 2.3% of respondents rated APIs they work with "very well documented."
API-first leaders rated documentation of APIs higher on average than others.
Improving API documentation
What does it take to improve documentation? Our respondents had insights. The most helpful enhancement API producers can make is to provide better examples in the documentation (66.4%), followed by sample code (62.8%), and standardization (53.0%). API consumers also find real-world use cases, better workflows, additional tools, and SDKs to be helpful, although to a lesser extent.
Meeting expectations—or not
When determining whether an API is—or is not—meeting expectations, API performance (54.9%) and usability of the API (54.8%) were almost inseparable as the top two responses.
API health and/or uptime was not too far behind in third (46.6%). The number of issues reported received mentions from 40.1% of respondents. Somewhat surprisingly, other quantitative measures like the number of applications, services, or programs accessing the API (21%), the number of users accessing the API (15.7%), and revenue generated by the API (10%) all clocked in lower than quality of developer experience (28.8%).
Respondents with 6+ years of API development experience were more likely to mention API performance (the top mention) than those with 0–5 years of experience.