Zuplo has launched a new suite of tools that rates the quality of your API, based on its OpenAPI specification. We put it through its paces and find it useful.

Designing and maintaining an API is still not an easy task to perform, and for that reason tooling is quintessential. We've examined such tools in the past, like OpenAPI Diff which tracks breaking changes made between API versions, Step CI which adds API testing inside the CI workflow, or AWS Smithy
with which you can model your APIs, generate code and documentation for clients and servers, as well as other artifacts, in many programming languages.

This time we look at "Rate My OpenAPI" by Zuplo. It is a suite of tools aimed at ensuring that your APIs meet high standards of quality and usability. This is done by evaluating your OpenAPI definition files to provide a comprehensive score based on four key categories:

• Documentation: Ensure your API is well-documented, making it easy for users to understand and use.
• SDK Generation: Verify that your API definition supports SDK generation, facilitating integration and usage in different programming languages.
• Security: Check for best practices and standards to ensure your API is secure and protected against common vulnerabilities.
• Completeness Ensure your API definition is complete, with all necessary endpoints, parameters, and responses accurately defined.

All these actions can be performed by using the suite which is comprised of a website, a CLI, a GitHub Action and an API, as such catering for every use case.

So, for instance, if you want to check an API's definition very quickly you can head for the website. On the other hand if you want to include the checks inside your CI workflow you go for the Github action.

To put it to test quickly we used the website and checked an example report generated for Zapier's Natural Language Actions (NLA) API - Beta 1. 0. 0.

The overall score was low, just 60%, and the associated summary was that:

Your API has some issues that need attention. There are 4 occurrences of missing trailing slashes, 15 occurrences of invalid schema examples (seriously?), and a whopping 8 occurrences of undefined error responses. Also, don't get me started on the 8 occurrences of rate limit issues. Get your act together, API creator!

This was followed by the details view, split into four categories:

• Documentation
• Completeness
• SDK Generation
• Security

and their accompanying issues rated into Warn, Info and Hint.

For instance in the Completeness category we got a few issues, such as :

• Warn:Top level spec `tags` must not be empty, and must be an array: `tags`, is missing and is required
• Info:Operation must define at least one 4xx error response
• Hint:Tags for `get` operation at path `/api/v1/configuration-link/` are missing

Clicking on an issue it expands to the actual lines of the API's definition line explaining the problem in more detail as well as making suggestions on how to fix it.

If you fancy the CLI way you can install it with :

npm install -g rmoa

After getting your Zuplo API Key, you can put the tool in action in for instance lint the document as :

rmoa lint --filename <openapi-filename> --api-key <API_KEY>

If you prefer, there's also detailed instructions on setting up an Github Action as well as using the Zulpo API. 

In any case, Rate My OpenAPI gives you some superior options in stress testing your OpenAPI defined APIs.

More Information

Rate My OpenAPI Github

Website

Related Articles

OpenAPI Diff Prevents API Breakages

Step CI - The API Quality Assurance Framework

Model Your APIs With AWS Smithy  

To be informed about new articles on I Programmer, sign up for our weekly newsletter, subscribe to the RSS feed and follow us on Twitter, Facebook or Linkedin.

Comments

Make a Comment or View Existing Comments Using Disqus

or email your comment to: comments@i-programmer.info