2020 State of the API Report - My Own Thoughts

This morning whilst going through my emails, noticed in my inbox an email titled The 2020 State of the API Report Is Here. As an API author, practitioner and product owner, this immediately caught my attention and naturally went straight into reading the content of the email.

And well, what I read did not disappoint. The report is the result of interviewing more than 13.5k industry professionals who are in one way or another dealing with APIs.

Kudos to Postman and the API Evangelist for this remarkable contribution (and all of the effort am sure went into putting this together).

Here is the link to the report:


Following my own thoughts / remarks whilst literally going through the report section by section. I am sharing it in case anyone may finds it interesting. I just want to reiterate that these are my own thoughts so you may or may not agree, and that's ok!

Key Findings

Broadly agree with all key findings, however there was one conclusion that I found peculiarly interesting:

The four most important factors individuals consider before integration with an API are reliability (71.6%), security (71.0%), performance (70.9%), and documentation (70.3%).

Whereas these findings make a lot of sense overall and are consistent with my own personal experience, I am a bit surprised that two key factors didn't make it to the top. These two are API breath of functionality and API commercials. There could be multiple reasons on why these didn't make it to the top however I rather talk about why I personally feel these are crucial factors:

API breath of functionality is basically nothing but the business capabilities offered by an API. At the end of the day, I will not use an API that doesn't offer the business capabilities required to satisfy my functional needs. It may be the best documented API in the world, but if it doesn't do what I need it to do, then I won't use it.  Yes, it relates to documentation of course, but different nonetheless.

API commercials, things like API payment model (e.g. pay per call, freemium, subscription tiers, transaction fee, etc), T's and C's and SLA's that although may not be of too much interest e.g. to API designers and developers, they will certainly be of interest for parties involved in consuming public APIs and having to pay.

For example, if am building a solution that requires Forex Exchange, instead of building my own forex exchange capability from scratch, I may adopt a public API that does this for me so I can realise this capability quicker and go to market quicker. However there are several forex exchange APIs out there and therefore I will likely pick the one that best satisfies my needs, at the best price and best commercial terms (and yes, "best" is subjective and depends in the context, but I hope you get my point).

The Rise of API-First

Results are interesting indeed and also consistent with my own experiences. Let me elaborate why:

There are several use cases for APIs out there, however one I've recently seen a lot is the auto-generation of REST APIs based on legacy interfaces like SOAP. So without judging whether this is the right thing to do or not (as this really depends on many factors), fact remains that for people involved in this type of implementation, API-first won't make a lot of sense.

To be clear, I am a huge fan of API first, and I personally find API blueprint to be an excellent notation for defining an API especially when working together with functional analysts who are less technical. Regardless of whether or not API Blueprint is a popular notation, I find it to be very intuitive and human friendly and even if the exposed API spec might not end up being API blueprint but OAS 2 or 3 (meaning there is an additional overhead to generate or convert to OAS), the productivity gained in early stages of the API design, are IMHO, worth doing. I also know many that agree with me on this.

Who Works with APIs

Not surprised at all that full-stack developers appear as the #1 most popular role working with APIs. In fact, this is the reason why in the past I've targeted many developer conferences such as Devoxx, Oracle Code, Java2Days, to name a few, to talk about API design and implementation rather than just targeting API specific conferences where audience already knows a lot about APIs (though I like these too!).

Furthermore, I think the results reflect the fact that modern software development (e.g. based on MVVM patterns or related) require APIs full stop. And now that I work for a software company developing SaaS products, I can say this with even more confidence.... APIs are crucial for any SaaS product, yes I know, not news! :)

Having said that, I think there is one key role that is not listed, which I think is also crucial and worthy perhaps of including in subsequent surveys. And that is the API Product Owner / API Product Manager. As APIs become commercial products on their own right, this will (or should) result in the organisation making certain individuals responsible and accountable for the success of this (API) product. My team and I in Oracle Hospitality are such example. But we're not alone. I know of many organisations that have such roles formalised as well. I think it would be interesting to see how many organisations have actually formalised this role as for me personally it means that such organisations are ahead in their API business strategies.

A Day, Week, or Year in the Life

Related to my previous answer, I think this question highly depends on the role of person interviewed in the sense that yes, engineers will of course spend majority of their time writing code (and if that's not the case I would be worried and they would be bored) however API product managers/owners will also spend most of their time working with API design, API commercials, API marketing, API community support, API/Platform feature analysis, to name just a few.

API Strategies

The results of the first section, Internal vs partner vs external, I feel highly depends on the actual industry. Not questioning the results overall, but I think results can vary depending on the industry. In Hospitality for example, I would say that Open APIs are on a huge rise given the nature of the business and actors involved e.g. to be able to book a hotel room in booking.com or expedia, these two OTAs first need to get hold of availability, room inventory and price data.... which in most of the cases is supplied via APIs -perhaps not public, but partner (though partner could also be public IMHO if any partner can just openly subscribe and start using the API without prior approvals or what not). There are many other examples in the Hospitality industry btw am just not expanding further.

Another remark I have about this section is related to what I said earlier regarding Key Findings. I personally feel that API breath of functionality and API Commercials are crucial aspects for any API Product Owner having to deal with a commercial API product -in addition to the ones already listed that is. For example, looking at the survey results, Pricing/Uptime/Performance are all areas that have got to be covered somehow in the API SLA's/Ts & C's. For example, if am paying to consume API X, then I expect the API to behave in accordance to the contract, which could imply response times of not more than e.g. 1s, and 99.98% uptime.

Executing on APIs

I couldn't agree more that lack of time is the #1 obstacle in producing what I like to call a good API (though I admit what a 'good API'  actually is, is probably a topic for another blog post!). In my experience there are multiple factors contributing to this, but I think a key one is competing internal priorities. At the end of the day, API management as a discipline remains a relatively new discipline especially to the business. So when business compare priorities is important to have someone, ideally an API Product Managers, ensuring that API related priorities are well understood in business terms. If such role doesn't exist then of course this is far more challenging accomplish and API priorities will likely lose against other priorities.

Reading further, didn't quite understand the results of the Collaborating on APIs section... For example a shared URL could point to API Artifacts in GitHub/Gitlab/Bitbucket or API documentation in a portal. Having said that, it is interesting to see that sharing artifacts published in source repositories e.g. GitHub, are more popular than API documentation in a portal. Although not by far. For me this is an interesting take away as I conclude that this could means: publish API in both places and let your audience pick which one to use....

On the API Change Management section, as I said before in Twitter, I favour a versionless API approach such as the one described in this article by Z. That said, what the survey results reflect in my view is practitioners rely on both source control and API versioning when dealing with API change management. Using Git makes it a lot easier to track change and compare new/old specs for example (or even adopt GitFlows to add some governance, e.g. PR steps, in the change control process). So I would say Git is perhaps more useful at design-time. Whereas API versioning has a greater impact at runtime as it can directly impacts consuming applications. But again, I my opinion, both are required.

I can really really relate to the results of the API Documentation survey. And I can summarise my interpretation of the results with the following quote:

"Perfect is the Enemy of the Good" - Voltaire

This survey section when combined with the top result of the next one, Improving API documentation, which is 'better examples', one can easily conclude what should be the priority when documenting APIs.

And last but not least the Meeting expectations—or not section, which for me is more of an implementation concern, is very clear to me that performance related concerns are a top concern, which in the case of public APIs, has a direct relation to API commercials hence my earlier point.

Tooling for APIs and Development

The results of the API tools survey also make sense to me (Postman  being the most popular tool for PAI development). My only comment here would be that even though I work for Oracle and I am indeed a big fan of Oracle Apiary (ok there is a bit of bias here!),  I am in fact also a big fan of Postman and we actually use both in a complementary way. I would say that Postman is a very good complement to many of the tools also listed in the section and wouldn't be surprised if many organisations using are also complementing their API Platform capabilities with Postman.

I also find the result of the Platform vs separate tools section quite interesting. In my years as a consultant, this was indeed a very popular recommended approach and it resonated well with customers as it delivers a good balance of cost/benefits.

Skipping some of the other sections and jumping into DevOps tooling, not necessarily surprised that Jenkins is the most popular tool but just wonder how much of this is just because Jenkins has been out there for a while and is the tool most people are familiar with. I am personally interested in seeing how the popularity of CICD pipelines capabilities now embedded in source repositories like GitHub or Gitlab increase in popularity. For example, GitHub actions is a fairly new capability and is already very popular according to the survey result.... so reading between the lines....

In the Deploying APIs I would say something related to my previous point, giving the increased popularity of Infrastructure as Code as an approach, not surprised that CICD pipelines is the most popular way to deploy APIs. In fact, I would encourage to do it this way if not done already. I would go beyond and say that an API Platform that does not offer one way or another the ability to deploy APIs via pipeline, is in my opinion, missing a key capability.

API Technologies

The Architectural style section, perhaps the most controversial question in communities of API practitioners (and one that always reminds me of the VHS vs Betamax discussion of back in the days) I kinda feel that the survey question was perhaps too broad and perhaps not comparing apples with apples.

This is just my opinion of course, but I would have for example split sync APIs with Async APIs architectural styles. For example there is a reason many call Webhooks are often referred to as RESTHooks. In GraphQL for example, many popular implementations of GraphQL Subscriptions and LiveQueries actually make use of WebSocket as transport protocol (as GraphQL doesn't impose a transport).

Nevertheless what I conclude is that REST remains the most popular architectural style implemented today for synchronous APIs, and WebHooks for Async. With GraphQL and WebSocket increasing in popularity rapidly.

Going further, in the case of Sync APIs, I think the results resemble to an extend what one can find in tools like Stack Overflow Trends (which in my view is one of the best tools to understand tech trends based on actual development adoption). See for example:

Source: https://insights.stackoverflow.com/trends?tags=rest%2Cgraphql

As it can be seen, yes REST remains more popular but trend is downwards as opposed to GraphQL where trend is upwards. And the gap is closing.

In the case of Async APIs however, Stack Overflow tells a different story. But is a tricky one because Webhook is not a transport protocol but rather an Architectural approach, whereas WebSocket is a transport protocol. So perhaps a bit of an apples/bananas comparison...

Source: https://insights.stackoverflow.com/trends?tags=webhooks%2Cwebsocket

I recommend my Event-driven API Strategies: from WebHooks to GraphQL Subscriptions recording from The 2019 Nordic APIs Platform Summit as I discussed this topic in far more detail. Below a diagram you may find useful from that same presentation.

Regarding the API Specifications survey result, again I personally wouldn't have mixed data structure specs (e.g. JSON Schema, Avro, Protobuff, etc) with API definition specifications such as Swagger, Open API 3.0, GraphQL SchemaAPI Blueprint. Reason being is that I feel it can confuse people that aren't fully familiar with the concerns addressed by each of these specs. Having said that, I feel results make sense,  OAS 2.0 is by far the most popular protocol out there with both OAS 3 and GraphQL catching up fast (and I wished API Blueprint as well at least just for early stages of API design).

The Future of APIs

Ok, now I may sound a bit like a broken record, however I feel that in the Future technologies survey results, again I wouldn't have mixed API implementation technologies with API Architecture Style related technologies. I say this because GraphQL, HTTP/2, Event-driven APIs can all be implemented as microservices running in Kubernetes and all with Service Meshes' like Istio. In fact this is exactly the way I've done it many times in the past, and by no means am alone in doing it this way....

But have to agree, Microservices Architecture represents in my opinion, the best Architectural approach to implement APIs. In fact in my book Enterprise API Management I have many pages and dedicated sections covering the many capabilities and patterns related to implementing APIs based on a microservices architecture.

Having said all that, the survey results of this section are really interesting in that one can also interpret that Microservices with GraphQL are perhaps the most popular combination... I would've thought that HTTP/2 and gRPC were perhaps more popular amongst microservices practitioners, but hey, this is exactly one of the reasons I found this survey really insightful.

APIs and Business Initiatives

One illustration came to mind when reading the results of this section and I'll say no more. I think we're all a bit over the top with COVID related discussions:

Learning about APIs

The results of this last section were in fact another eye opener for me. And although it shouldn't have come as a surprise that "learning on the job from colleagues" was the most popular way to learn about APIs (after all, a lot of my time goes in sharing knowledge and learning from others), it never occured to me that it was even more important than learning from documentation (second most rated entry). So I am pleased that I know this now. I will almost immediately put this into practice by emphasizing to my team and peers the importance of sharing knowledge with our colleagues -of course in complement to proper documentation!!

Thanks again  Postman and the API Evangelist for this great report, and hope you find my comments of value for future surveys :)