Top API Specification Trends: 2019-2022

Unsurprisingly, the pandemic-ridden era has fueled the rise of APIs in the world. What is more interesting, however, is that with the rise of APIs, a rise in the number of API specification documents has been observed as well. It leads us to believe that more people are adapting to the design-first approach for building APIs, resulting in intriguing API specification trends.

An API specification document is a machine-readable description of an API or service that describes its endpoints, data models, and other related information. In case you are wondering why you need an API description document in the first place, that is an entirely different topic that I have discussed in the blog Why Your API Needs Machine-Readable Description.

This blog sheds some light on the top API specification trends observed over the past 3 years. You can expect data around which API specification formats were most popular, ones that seem to be emerging over time, and those that are showing signs of imminent death. The trends are based on data collected from APIs imported or transformed by unique users on APIMatic.

Postman Collections - Most Popular Input

In the last 3 years, nearly 30,000 users brought only Postman Collections as input into APIMatic either to transform their API specifications to some other format or to generate SDKs/Developer portals. The second-largest number of input API specifications were mainly OpenAPI files.

Many developers test their APIs on Postman which makes it their first choice to store all API-related information. As a next step, if they want to set up a developer experience (DX) platform for their end-users with API documentation and SDKs, it is easier for them to export their stored API information in the form of Postman Collections and use them to generate the required DX kits. This explains the big number of users bringing in Postman Collections as input into APIMatic as well. 

However, the Postman Collection files are structured around making API calls and lack a proper type system to define data more precisely. This makes it a slightly tricky format to deal with when generating good quality SDKs and language-specific documentation, however, you can tackle those issues by following this detailed blog on How to Generate Quality API Documentation & SDKs from Your Postman Collections.

The Rise and Fall of API Specification Formats 

In just 3 years, some popular formats have lost some of their fame while others have risen to take the throne. 

Insomnia - An Emerging Format

Soon after Kong acquired Insomnia at the end of 2019, the Insomnia specification imports nearly quadrupled in APIMatic. Being quite a newer format, the imports remained quite low as compared to Postman Collections (it being the closest alternative to Insomnia). However, its usage has been increasing steadily ever since.

OpenAPI v3.0 Imports Have (Finally) Overtaken v2.0

Contrary to the API Specifications statistics of Postman 2021 State of the API Report, APIMatic saw an increase in the number of imports of the newer OpenAPI version v3.0 as compared to v2.0.

As can be seen from the graph above, around the start of 2019, the OpenAPI v3.0 imports were initially less than those of v2.0 (also known as Swagger v2.0). Then, they stayed nearly equal for around four months and eventually rose well above them after August 2019. Meanwhile, the imports of v2.0 slowly declined and are expected to continue their downward trend as more and more people adapt to the newer version. 

OpenAPI v3.1 - Still in Infancy

OpenAPI announced its release of the newer version v3.1 in early February 2021 with APIMatic releasing support for it in late September. 

As was obvious in the case of OpenAPI v3.0 vs v2.0 adoption rates, it takes time for tools and the end-users to adapt to newer versions of specifications. There are still tools out there that continue supporting v2.0 and have yet to add support for OpenAPI v3.0. Even when tools do eventually start supporting a new version, it takes more time for end-users to migrate their existing specifications to it and even more time until they start utilizing the newer features fully. 

Therefore, we expect the OpenAPI v3.1 usage to remain quite low for some time. However, with full support for JSON schema and other shiny features, the adoption will open up interesting new possibilities in the future for tools and platforms alike. 

To learn more about APIMatic’s support for OpenAPI v3.1, check out the blog on OpenAPI 3.1 – What’s New, and How to Migrate to/from Other API Specs?

RAML, API Blueprint, WADL are Fading

• RAML’s latest version (v1.0) was released in 2016. It is the primary format used in the Mulesoft Anypoint platform. 
• API Blueprint is the primary format used in the Apiary platform (acquired by Oracle) and was published around 2013. 
• SoapUI users may be familiar with WADL as well, which is a format as old as 2009. 

RAML or OpenAPI on Anypoint Platform - Now a Choice

RAML v1.0 offers nearly all of the features offered by OpenAPI v3.0. However, while Mulesoft claims that RAML helps you add modularity to your API specification documents, its prime goal is helping define APIs and not modeling API specifications. Mulesoft, therefore, urges users to make use of both OpenAPI and RAML to achieve their goals. 

The trends of the past 3 years talk a little differently and seem to indicate that RAML is slowly losing popularity. RAML may remain a choice for Anypoint users, especially those managing APIs completely on their platform. However, the number of such users seems to be largely decreasing over time as Anypoint itself started offering support for OpenAPI v3.0 in 2021, and more API management platforms with support for OpenAPI are emerging as well. 

API Blueprint - No Longer Actively Maintained

Thanks to Markdown, API Blueprint provided a way to write an API specification document that is more human-friendly. However, the downside of this is a compromise on its ability to be machine-readable. It also lacks some of the advanced features offered by OpenAPI.

Interestingly though, API Blueprint is no longer actively maintained since 2019. This may be attributed to Apiary announcing experimental support for OpenAPI v3.0 in early 2019 and can explain why, since then, we are seeing a downward trend in the usage of API Blueprint.  

WADL is an XML-based format for services that work over HTTP. With an increase in REST APIs, JSON has become the most common data exchange format which is best defined using JSON schemas that RAML and OpenAPI support, whereas WADL offers support for only XML schemas.

APIs that exchange XML may still benefit from WADL, though based on the trends the number of such APIs seem to be decreasing over time which likely explains the decline in the usage of WADL as well.

API Specification Transformation Trends

APIMatic offers API Transformer as a free tool to help you transform from one API specification format to another. We support all popular formats including OpenAPI, Postman Collections, RAML, and more. 

I’ll share some interesting trends observed in the API Transformer usage in the 2019-2022 time period. Previously, we conducted similar insights for API Transformer for the years 2017 and 2018. If you are interested, you can check them out here:

• API Transformer Insights 2018 
• API Transformer Insights 2017

OpenAPI/Swagger v2.0 - Most Exported Format

As discussed earlier, the number of OpenAPI v3.0 imports surpassed OpenAPI v2.0 imports in the past 3 years. However, quite surprisingly, the number of OpenAPI v2.0 exports remained quite high as ever, or perhaps more than before. This at least supported the Postman 2021 State of the API Report and my shock was nearly on the same levels as the API Handyman.

If you head over to the list of popular OpenAPI tools, you’ll notice that almost all tools now support OpenAPI v3.0 and there are a large number of tools that don’t even support OpenAPI v2.0 anymore. So, why are people preferring to convert their API specifications to OpenAPI v2.0? Some people are even downgrading from OpenAPI v3.0 to v2.0 (more on that later). 

While the exact reason is not entirely clear, the apparent reason revolves around the quality of support for OpenAPI v3.0 in tools. OpenAPI v2.0 has been around for much longer than OpenAPI v3.0 so though tools claim to support OpenAPI v3.0 their support for OpenAPI v2.0 may be much more stable and dependable. It is also possible that people are using legacy tools that still only support OpenAPI v2.0.

Top API Specification Transformation Use-Cases

Over the past three years, some interesting use-cases surrounding API specification transformations have emerged.

Postman to OpenAPI

Postman's APIMatic integration offers its Pro users the ability to convert Postman Collections to any format of their choice. A large number of transformations from Postman Collections can be attributed to that. Nearly 40% of transformations saw users trying to convert their Postman Collection files to OpenAPI. 

As far as the conversion to OpenAPI is concerned, it opens up a large set of tools for Postman users from where they can generate output varying from simple API documentation to feature-packed API developer experience portals with SDKs, live code samples, etc. In other words, converting to OpenAPI helps them manage their APIs better during the later stages of the API lifecycle (e.g. API consumption).

15% of the transformations show that users who are already using the newer OpenAPI v3 versions feel the need to downgrade back to the older versions, particularly to OpenAPI v2.0. The only plausible reason seems to be the lack of proper support for OpenAPI v3.0 in tooling that they are looking to use.

With more benefits, an increasing number of users are looking to migrate their legacy APIs to REST. While the migration is not a single step process, since every SOAP API is accompanied by a WSDL specification/contract, conversion of WSDL to a REST-supporting format (e.g OpenAPI, RAML, etc.) can serve as a starting point. It can give an idea of what the final API can look like. 

In APIMatic, API Transformer offers the SOAP to REST conversion, to its users. Based on the data collected, 8% of the transformations performed by unique users converted their WSDL files to an API specification that supported only REST APIs (e.g. OpenAPI, RAML, WADL, API Blueprint, etc.) in the past three years.

With the increase in Insomnia specification imports, an increase in the number of transformations from Insomnia to Postman Collections has also been observed, constituting about 4% of the total transformations performed by unique users. 

Insomnia is the closest alternative to Postman, offering very similar features. However, Postman has been around for quite some time now and hosts a large user base whereas Insomnia is relatively newer. The need to convert between the two formats likely boils down to varying ease of use of both tools as well as personal preference. If, within a single team of your API program you have members who prefer Postman while others prefer Insomnia, then, to ensure smooth collaboration between these members, conversion between the two formats can present itself as a necessary step.

Invalid API Specifications

Not all the inputs we receive in APIMatic are valid API specification documents. A small portion of them have a few common mistakes or violate the standards one way or another.

Comparing Success vs Failure Ratio

Looking at the API specification trends, it is interesting to note that API specification documents that have some form of manual intervention involved showed a greater tendency to be invalid (e.g. RAML, OpenAPI) as compared to API specification documents that are compiled and generated purely by tools (e.g. Postman Collections, Insomnia). 

Out of the total RAML files received by APIMatic in the last three years, nearly 38% had some form of issue. This is in sharp contrast to Postman Collections where out of the total files we received, only 0.99% were invalid.

Common Causes of Invalidity

The causes of invalidity vary greatly depending on the format, however, some of the most common ones are listed below:

1. Unresolvable references are the topmost reason for failures. API specifications have different ways to reference other components within the same file or externally. An unresolvable reference is one where the component being referenced either does not exist or exists with a different name or the path to the component is invalid.
2. Syntax issues are the second most common reason for failures. A trailing comma in JSON, bad indentation in YAML, or unclosed tag in XML are all examples of invalid syntax.
3. Often users have specifications where types of components do not match the expected type set by the standards e.g. RAML v1.0 standard sets the type of property scopes as a “list” of strings yet plenty of developers declare it as a simple string.

If you often run into issues like the above, I recommend going through this series of blogs on how to avoid:

• Common mistakes developers make in their OpenAPI v3 files
• Common mistakes developers make in their RAML files
• Common mistakes developers make in their API Blueprint files

In case that doesn’t help, feel free to try some of our troubleshooting tips and FAQs. 

Conclusion

Recent API specification trends show a mass convergence of the API community towards accepting OpenAPI as the standard for describing REST API services. Postman is expected to continue complementing OpenAPI with its API testing features though it might face some competition from Insomnia in the longer run. 

While new API technologies are emerging like GraphQL, GRPC, and more, REST remains the most popular, with legacy APIs trying to catch up. These trends are expected to play a key role in the evolution of API specifications in 2022 and beyond.