A Year with API Transformer

Developers today are actively seeking relevant tools and frameworks in order to make their API design and consumption process as easy and efficient as possible. An important part of this process is describing the API in any of the available specification formats. And since each of the API description formats come with their own toolset, the need to be able to convert between different formats is growing rapidly. This is where API Transformer comes into play. It offers a tool called “Convertron” which has helped many users transform their API description files from one format to another. Many popular formats like OpenAPI, RAML, etc. are supported.

Over the years, API Transformer has evolved quite a lot. In particular, the year 2017 saw some important additions to the tool like the newly added support for OpenAPI 3  and WSDL. Many improvements were also made to the existing format parsers in which, without any doubt, the valuable feedback from our amazing users played a vital role. The year has flown away but has left behind some interesting trends and patterns that we plan to share with you today in this blog.

Trends from 2017

For each aspect, two kinds of data will be analyzed. One will take into account all events that occurred irrespective of the users performing these events. However, we have a handful of users who perform thousands of conversions every month. The first data gets largely skewed because of these conversions. So in the second data, to get a better picture, we try to remove this skewed behavior of the data by considering only unique events per user.

Most Common Formats Brought In By Developers

Out of the total imported files on Transformer (approximately 94,000), 50% were Postman 1.0 files, 25% were Postman 2.X while only 6% were OpenAPI 2.0. The second graph does not consider redundant format conversions per user e.g. if a user converted fifty Postman 1.0 and ten OpenAPI 2.0 files, he converted two unique format files (one Postman and one OpenAPI). Elimination of this redundancy shows that 24% of the imported files were defined using OpenAPI 2.0, 20% were using Postman 2.X while 10% were using WSDL. The rest falls in the smaller chunks. So the most common formats brought in by developers were OpenAPI and Postman.

Most Common Formats Developers Loved Exporting To

52% of the API description files were exported to API Blueprint while 35% to OpenAPI 2.0. Eliminating multiple exports to the same format per user, we observed that 55.5% of the files were exported to OpenAPI 2.0 while 9% to RAML 1.0. API Blueprint was not very dominant in this second case. Overall, OpenAPI 2.0 seemed to take the lead for the format that developers wanted to play around with.

The choice of the format when exporting could have been related to several factors like size of the community, tools, and frameworks available, strong documentation, and availability of a newer and stable version with more features, to name a few. OpenAPI 2.0 and Postman 2.0/2.1 are a natural preference over their older versions (OpenAPI 1.2, Postman 1.0). Very few users prefer to export to WADL or WSDL because of limited usage and tooling.

Most Common Format Conversions

We also looked at the top ten import-export mappings to understand which conversions are most popular. For the total conversions performed, the most common conversion seen was from Postman 1.0 to API Blueprint (approx 45,000 conversions) whereas if we eliminate non-unique mappings per user, import from Postman 2.X to OpenAPI 2.0 was found to be the most common (approx 530). This shows that a lot of developers prefer Transformer for converting from Postman to other API description formats.

Geographical Usage of Formats

From the above graphs, you can see that users of Transformer are distributed far and wide into various geographical regions of the world. We had some users performing thousands of conversions every month from India and they constitute 52% of the total conversions represented in the first case. If multiple conversions from the same location per user are ignored, we see that 24% of the conversions occurred from the US while only 10% were performed from India. Hence, the majority of our users using Transformer in 2017 were based in the US and India.

Note that for these graphs we eliminated data of conversions in which the locations were unknown.

Most Common Formats That Failed To Transform

Some of the users failed to transform their files (approx 8,000 which is roughly 8% of the total conversions performed). 35% of the total failed conversions were invalid/unsupported (more on this later) while 30% were RAML files (0.8/1.0) and 18% were OpenAPI files (1.X/2.0). By removing redundant failures of the same format per user, a big 44% of the chunk of failures belonged to the invalid/unsupported, 20% belonged to RAML(0.8/1.0) while 17% were OpenAPI files (1.X/2.0).

As you can see, a large portion of failures constitutes of the invalid/unsupported files. These were the files which were either:

• Not valid API description files e.g. HTML files, JSON response data, XML schema files OR
• Supported by Transformer but lacked necessary metadata that prevented proper identification e.g. API Blueprint files without “Format” and “Host” information. Some common mistakes also prevented proper identification of the files (invalid JSON, incomplete file, etc.) OR
• Not supported by Transformer in 2017 e.g. Insomnia

The rest of the conversions are largely attributed to RAML or OpenAPI files. A common cause for these is uploading a file containing external references without providing these references within the specification file.

Transformations via Web vs Transformations via API

API Transformer not only provides a web UI to users for performing conversions but also facilitates them by providing a simple API that offers the same functionality as the UI. In 2017, 76% of the total conversions were made using the API. However, by considering only unique web/API conversions per user shows that 96% of the conversions were made using the web interface.

Size of the APIs

For measuring the size of an API, we considered the number of endpoints in an API. Pretty much all the APIs had less than 300 endpoints. However, a very small portion (0.39% of the total conversions and 2.61% of the unique conversions per user) of large APIs also existed that had endpoints ranging above 300.

Conclusion

2017 was no doubt an exciting year offering intriguing insights into API Transformer. This year we plan to make Transformer even better by adding other commonly used formats like  Insomnia and by improving other areas of it as well. So, stay tuned!