API testing is an essential part of the development lifecycle. Not only can API testing expose common missteps in API design, performance, and security, but it can also help improve ongoing iterative improvement and design reviews. What is most important about this process is having trustworthy tools to perform the testing with.

Without testing, developers can feel lost trying to gauge quality or determine where there is room for improvement. One intriguing type of testing is OpenAPI specification scanning, which can reveal some interesting insights into how the API is structured and any hiccups to fix. Live testing can take this further to verify the API actually performs well when sent production requests.

API Insights is a free tool from Treblle, an API management company that acts as a “mission control for your APIs.” The API Insights tool quickly scans your OpenAPI specification files and can give you actionable insights about your API’s design, performance, and security. Below, we’ll examine what it does and how it can benefit your testing and an iterative API design approach.

The API Insights Tool

As the Treblle team describes, the API Insights tool is designed to be simple and accessible. All users have to do is link to their specification (or upload their specification file) via the API Insights webpage. The site will then process the specification and score the API on three considerations:

• Design: This score measures the structure of the underlying API, determining whether it is well-designed.
• Performance: This measures the speed and efficiency of the API and offers improvement areas for both.
• Security: This tells you how secure your API is, evaluating common security concerns.

Example Insights Report

Let’s perform a test report to look at the average experience using API Insights. For this insights report, we’re going to target the GitHub OpenAPI Specification.

Step 1: Requesting Insights

Requesting insights is quite easy. Simply navigate to the API Insights webpage and enter the URL for review. In this case, we are using the following URL:

https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.json

Step 2: Review The Findings

After clicking Get Insights, the following report is generated. This top-level report is very helpful in giving you some general feedback as to where the API currently stands.

One thing to note about this score is that it reflects what API Insights views as the most critical pieces in your codebase. There may be some use cases in which design choices are purposefully deprioritized or where performance may not be a core concern. In the context of these scores, however, they are considered against a best-case scenario. As such, further details are needed to evaluate the overall API score than can be gleaned on first glance.

Step 3: Dive Deeper

By scrolling to the lower part of this report, you can dive into specific instances that have impacted the score.

You can start to get an idea of the most significant elements impacting your score in this view, but you can also identify places that may not be valid for your specific use case. For instance, due to the way this API Specification was hosted, the version is shared in text but is not part of the specific URL for accessing that data. Accordingly, while the concept is valid, this may not be as significant a problem as is highlighted in this view.

By expanding each category, you can get a summary of what was tested. While this gives you some insight into what may affect your score, it does not provide exact locations or guidance on how to fix them. Nevertheless, this can provide a head start toward identifying and resolving problems. Or, in the case of problems that are detected that aren’t really problems, they can help you start establishing greater clarity so that you do not trigger a false positive.

Sometimes, a test is skipped depending on how the API specification is rendered or utilized. In this case, the “Response size” test was skipped. In such a scenario, this has no impact on the overall score.

The final section of this test is for security and is the most likely place to generate false positives. For example, many systems may have Authorization as part of a secondary API. In those cases, if you are testing a single API specification that is itself part of a more extensive collection of microservices, you may see a negative result.

Nevertheless, this still gives some insight into the current state of security on your system and helps provide some peace of mind for common issues.

Additional Examples

The following are some additional API specifications tested against the API Insights tool.

Spotify

Results

The Spotify OpenAPI specification file does okay on design, but has some security and performance flaws. Notably, how it implements rate limiting is obfuscated for the tool, leading to a fail grade. There is also a lack of a header set for content type, which ultimately results in a bit of complexity for services trying to understand how to interact with the data, even if the data is in an accepted format.

Design

Performance

Security

Stripe

Results

While Stripe performs decently overall, it follows some designs against best practices. Issues with noun usage, pluralization, and embedding iFrames result in generally poor results across the board. Issues in each category suggest that these fixes are pretty simple, but their impact could be significant if left untreated.

Design

Performance

Security

Conclusion

API Insights is a simple but powerful tool for developers to test their OpenAPI specifications against various common issues to ensure high performance. These sorts of one-off, purpose-built tools are becoming more popular, and while there is merit to advocating for the full use of a complete security and testing platform, the underlying value proposition of its API Insights engine is well-represented in this free and accessible resource. Also, for those who prefer to work within their IDE, API Insights also has a VS Code extension, as explained here.

What do you think of this solution? Let us know in the comments below!