The Who, What, and Why of API Specifications

Here at Cequence we have covered the ups and downs of API specs throughout the years. Discussions on what they are, who is (and regrettably isn’t) using them, and why they are important have been the subject of several blog posts on our site and around the web. We’ve discussed the OpenAPI Specification (OAS) and the different parts of the framework in the Cequence blog. Our goal is to demystify API specifications and help everyone get to a common understanding. These articles should help you understand the “what” of the OpenAPI specification. This isn’t the only format for API specification files, but it is the most widely used.

Common API Specification Terms

To complicate this topic slightly we also need to think about the three different terms that are used: API documentation, API specification, and API definition. The team over at Swagger has a great article about this topic that we’ll summarize here. API documentation is the reference manual for the API that is meant for people to read and understand how to work with the API. API specifications are written to explain to humans how the API functions and what specific output to expect. API definitions are machine-consumable and explain how the API functions and what to expect out of it in machine-readable format. Specification and definition are the two terms most likely to be used interchangeably, even though they are meant for different audiences. The most important thing to remember is that each of them is meant to help humans and machines understand how to use the API and what its functions are supposed to be.

Who Are API Specifications For?

As we move to the “who” of API specifications, it is generally thought that development teams and software engineers are the most likely groups that will need them, and you’d be correct. However, as APIs continue to be used more and more, teams like information security and security operations also need to know what is happening with their organization’s applications. Protecting sensitive data from leaking via an API is difficult if the teams aren’t sure where that sensitive data is in the application.

Why Do You Need API Specifications?

By some accounts, up to 64% of organizations do not have total coverage of their applications documented in a specification, which can leave organizations with major hurdles. In the 2023 Postman State of the API Report, development teams listed the lack of specifications as one of the obstacles to consuming APIs. 52% of respondents said lack of documentation was the biggest problem. Other top barriers included difficulty discovering APIs (32%). This shows that there is still an acute need for development teams but is even worse for security teams who may not have access to the documentation at all.

These statistics should make it much easier to understand the “why” of API specifications. In a blog post last year we discussed ten must-have things for an API security solution and specifications ranked number four on that list. Having a specification will help validate runtime behavior of the API and shine a bright light on the shadow APIs that we all hear about. When thinking about shadow APIs, how would a security analyst even know it was shadow if they don’t have a specification to tell them what the API is supposed to do in the first place? The difficulty stems from an age-old problem for development teams where the documentation is usually the last step in the process and the easiest to skip when time runs out. Some teams are moving to a schema-first approach to API development to shortcut the issues with lack of documentation. What are security teams to do when that isn’t the case for their organization? documentation is usually the last step in the process and the easiest to skip when time runs out. Some teams are moving to a schema-first approach to API development to short cut the issues with lack of documentation. What are security teams to do when that isn’t the case for their organization?

Cequence API Sentinel: An API Specification Compliance Solution

With Cequence API Sentinel, security can begin to solve that lack of documentation problem by taking the first step and creating their own API specification files from runtime traffic. As you’ll see below, I’ll take us from discovered data to full specification with accompanying API definition right from the console. Discovered APIs can be used to create an OAS 3.0 structured API Definition. Once generated this API Definition will be available under Applications: API Definitions to view, download, and update.

In the API Sentinel dashboard, we start with the Discovered endpoints in the inventory dashboard.

The inventory dashboard is where we will see all of the applications observed by the platform. The discovered section is the place where all transactions not identified by an API specification are located.

The next step is to open the filter panel and make sure that you have traffic for the endpoints that are being discovered.

API Sentinel uses runtime traffic to help us build out the API specification in the design wizard.

Now when we drill into the discovered applications, we will see the paths to the endpoints of interest. I want to build a spec for the books application, so I’ll select it and click on the Generate API Definition button.

There is a lot of data here that can be interesting to an analyst but for now we want to make sure that we know what this API is doing and document what we are seeing.

Now that we have the generation wizard running, we are going to fill in the spec details. If you know the service name, application owner, and host details you can fill them in here. The wizard will grab as much as possible during generation. If not, the SOC can start by using their own information. The only required field is Name.

This was for the book API so that is the name that I used.

The next step is to lock in the API path. There were four endpoints found in discovered here but not all four are a part of the books application. I fill in the Base path and then click the Lock Base path option.

Once that lock is set you’ll see that the last endpoint is now excluded.

The next step in the process is to set the type of authentication the platform should expect to see. There are three types supported in the wizard today, http, apiKey, oauth2. If there were authentication events observed in the traffic those would be listed here. If they aren’t or if you aren’t sure you can leave this section blank and continue.

An important note here: lack of authentication is a hit on OWASP top ten as API2. API Sentinel will help teams discover and find these unauthenticated endpoints.

Moving on to the next step in the wizard allows you to set any paths or parameters for the application.

Like in other sections, the wizard will set types and other items that have been observed. When you don’t have the details for the full application, this section can be skipped as well.

Finally, we get a preview of the spec that will be consumed in API Sentinel as a definition. We are also given the opportunity to add this to an existing group of definition files for our other applications. In this case, the books application is a standalone API and I can finish by clicking the Add button.

With that completed the books application will now move from discovered to published and if there are any changes in the future, I’ll be able to catch those pesky shadow APIs and act accordingly.

Want to Learn More?

Get started easily with a free API Security Assessment from Cequence. It’s easy, and there’s no obligation.