How to audit API step by step

API is an important software intermediary that enables the communication between two applications. It provides software flexibility, simplifies the designing process, and eases the management. When it comes to the software ecosystem, everything needs to keep up with the highest standards, because a well-planned ecosystem gives high comfort of using the services. The most effective way to recommend improvements is strong expertise. Read on to know how we conducted API and documentation audit step by step.

At first we decided to carry on the audit in a blackbox way of testing. It means that we didn’t have any access to the code or internal documentation. We based the audit mostly on the materials available on the website. At this stage, it was impossible to estimate the percentage coverage of our audit versus all of the API methods. Later, by gaining source code access, we were able to effectively prepare specifications of all controllers, APIs, and methods, as well as an audit plan. We classified errors and problems in the following categories:

The audit team found approximately 21 issues that are listed in the table below.

The last factor we paid attention to while conducting the audit was the overall impression of developers who worked with the API.
API audit: step by step
The most common conceptual visualization of the CI/CD process (also during API building) looks like this one below:

The disadvantage of this solution is the lack of a seamless transition from the API project and new functions to automatic tests, or the generation of documentation, examples in different languages, etc. Additionally, launching an interactive and very extensive documentation without automatic connection with the project or code will increase its costs. Installing each version will require a costly identification of potential code snippets that need to be changed. Therefore, we recommend the following project approach.

The API audit plan contained the following content:

Below are the modifications to the CI/CD process with new elements that automate validation, tests, and creating interactive documentation. These actions not only improve and tighten up the process – automation affects the pace of implementing new features.

In the second step, we refer to the use of tools that change the input and output definitions at the parameter name level without changing the business logic. There are 2 possibilities: target or transition version. We can implement API improvement at the code level (target) or at the additional layer level (translator/dispatcher).

At this stage, we created a detailed project (UX, technical SEO analysis) of a coherent Developer Center. Then we built a new Developer Center.

We chose 5 methods for the tests and described them using the meta language. In accordance with the chosen concept, we will be able to include the documentation and API compliance validation, automatic tests or interactive documentation in the CI/CD process. For this purpose, we used:

API Blueprint is a high level language for describing web APIs. The syntax is a combination of Markdown and MSON, and the files are saved with a .apib extension. Markdown is a lightweight text formatting syntax, and MSON is its extension used for describing data objects. The goal of the API Blueprint format is to enable the design-first philosophy  for REST APIs, however, the format works just as well for documenting existing APIs.

Apiary is an interesting tool that allows us to easily and quickly design an API. While waiting for an endpoint for our application, we can prepare and use appropriate actions ourselves and our development won’t stand still. With this tool, we can simply exchange knowledge within the team, present the requirements for the expected server responses, and prepare interactive documentation. This allows us to easily show the other part of the team how our endpoint should work. The only downside of the free version is the ever-growing project document, where scrolling through our Blueprint can be troublesome with more complicated actions. Nevertheless, we’re happy to use this tool for smaller purposes and encourage everyone to familiarize yourselves with it.

The screenshot below presents the main view of the documentation.

The panel on the left is a Table of Contents, which includes 3 chapters:

The Introduction section contains the information about how to set up everything to be able to use API – for example, how to authenticate or register to the system. The Reference section contains actual definitions of all the resources available in the API. Each object has its own section which includes a set of links to each method definition. The Data Structures section contains a list of all objects that are part of the API and their definitions, like parameters and types.

The screenshot below presents the main documentation view with an opened call method details and Try console panel. It shows the URL, URI parameters with description, headers for request and headers, example body, and scheme for response.

The screenshot below presents a call method details with a possibility to generate code examples (for the use in your application) in many popular programming languages. This helps to facilitate the process of integrating any application or system with the API platform via the API interface. Available languages are cURL, Java, JavaScript, Node.js, Perl, Python, PHP, Ruby, Go, C#, Visual Basic, Groovy, Objective-C, Swift.

The screenshot below presents the Try console panel which offers an opportunity to test API directly from the documentation. It allows us to put in custom parameters, header and body, and create fully customized request to the server. We can also call methods through mocked endpoints, which allows us to inspect all the traffic around the API.

Dredd reads API description and step by step validates whether API implementation replies with responses as they are described in the documentation.

The screenshot below present Dredd test results in a more readable form. They contain reports for all method calls with errors (if they occurred), any inconsistencies in the request or responses, and other valuable information which can help investigate problems with the API. Dredd can be also connected with any CI/CD tool which runs tests automatically when any changes are applied to the code.

Documentation is an essential part of any API. Without it, it is extremely difficult to find out what endpoints are available, what they are for and what parameters we can use. Such interactive documentation allows us not only to view the available endpoints, their parameters or schemes of returned values but also allows us to try them out. This is useful not only for finding the certain resource but also for calling it on request, which often turns out to be useful during development.

If you’d like to learn more about API audit, API Services or DevOps processes, check our website or read our blog: