6 min read

Blog thumbnail
Published on 03/21/2023
Last updated on 06/18/2024

APIClarity: Uploading an OpenAPI Specification 



This blog is part of the APIClarity How-To Series.

Uploading an OpenAPI Specification

In this blog, I’ll show you how to upload an OpenAPI spec to APIClarity to bolster your API security. To recap, an OpenAPI spec is a standard way to document an API and APIClarity uses it to compare incoming API traffic against what’s expected and allowed. An OpenAPI spec can either be uploaded, or APIClarity can reconstruct one from observed traffic (we’ll cover this in the next blog). 

Behind the Scenes 

Throughout the APIClarity blog series, we’ve been using Sock Shop as our sample microservice application. See the installation blog for specifics on setting up APIClarity with Sock Shop.

Sock Shop has API specs for each microservice, but they aren’t quite in OpenAPI format.  

Let’s start with this (for the catalogue service):

I converted it to OpenAPI3.0 here: Next, I set the version for the catalogue API spec ("1.0.0"). This is what we’ll use for our example. 

Upload the Spec 

In the APIClarity UI, go to the API Inventory tab (circled in green in Figure 1 below).

API Inventory Tab From Dashboard UI
Figure 1: Choose API Inventory Tab From Dashboard UI

In the API inventory list, select the one for your microservice application. In this case, we’ll select “catalogue.sock-shop” (circled in green in Figure 2). 

catalogue.sock-shop” from API Inventory
Figure 2: Select "catalogue.sock-shop" from API Inventory

On the next screen, click “browse” (circled in green in Figure 3) to upload your OpenAPI spec file. 

Click “browse” to Choose Spec File
Figure 3: Click "browse" to Choose Spec File

If there are any errors in the spec file, they’ll be reported here. Click Finish (circled in green in Figure 4).

Click “Finish” to Upload Spec
Figure 4: Click "Finish" to Upload Spec

Once the API spec is uploaded, you can either look through the APIs directly on the APIClarity UI or in Swagger. Click on "default-tag" (circled in green in Figure 5) on the APIClarity UI.  

Select “default-tag”
Figure 5: Select "default-tag"

You’ll see a list of API endpoints and parameters. Click the arrow next to one of them (Figure 6). 

Select API Endpoint
Figure 6: Select API Endpoint

If you click on a particular endpoint, you’ll see a “hit count” graph of the number of times the API has been called (e.g. Figure 7). 

Hit Count for API Endpoint
Figure 7: Hit Count for API Endpoint

To see the API spec in Swagger, click on "see on Swagger" (circled in green in Figure 8 below). Note that no information is leaving your Kubernetes cluster in order to get to the Swagger UI. Everything stays local to the cluster. 

see on Swagger
Figure 8: Click "see on Swagger"

Each API endpoint is listed in Swagger (e.g. Figure 9). 

Swagger UI Listing API Endpoints
Figure 9: Swagger UI Listing API Endpoints

Click on each endpoint to see example request parameters and an example response (e.g. Figure 10). 

Swagger UI API Endpoint Parameters
Figure 10: Swagger UI API Endpoint Parameters

At the bottom, in the Schemas pane, each API response schema is provided (e.g. Figure 11). 

Swagger UI Schemas Detail
Figure 11: Swagger UI Schemas Detail

Provided Spec

Now that an OpenAPI spec has been uploaded, you can see it listed as a “Provided Spec” on the API Inventory screen (in Figure 12 below, the “catalogue.sock-shop” APIs are listed as having a provided spec). 

API Inventory UI Showing Provided Spec
Figure 12: API Inventory UI Showing Provided Spec

Spec Differences 

Now that the OpenAPI spec for the catalogue application has been uploaded, APIClarity can detect spec differences between the uploaded spec and the observed API traffic.  

APIClarity reports spec differences in the UI with this symbol:  

Cisco Tech Blog Icon

If you’ve really been paying attention in this blog, you may have seen spec differences being reported in some of the UI screens above. 

In my testing, a spec difference was reported in the API Events tab (circled in green in Figure 13). 

API Events Tab From Dashboard UI
Figure 13: Choose API Events Tab From Dashboard UI

There’s a spec difference warning in the “Spec Diff” column (Figure 14).  

API Events UI Showing Spec Diff
Figure 14: API Events UI Showing Spec Diff

If I click on that row, I can drill down into the specific catalogue API call that had an unexpected spec difference (Figure 15). 

Spec Difference UI
Figure 15: Spec Difference UI

Here, we can see that the "/catalogue/{id}" API was called without specifying an ID, which is a required parameter for the API.  Worse than that, the catalogue API returned a 200 (OK) response and actually listed an object ID. This is a potential Broken Object-Level Authorization (BOLA) attack, because an object ID was given in a response without first being requested. We’ve found our first data leak and BOLA!  We’ll talk about BOLAs in more detail in a future blog on the APIClarity Trace Analyzer. 

The good news is that Sock Shop is just a demo application, but it’s pretty cool that APIClarity found a weakness in its API security. Hopefully you’re not using Sock Shop to sell socks in the cloud. 


Congrats, you have now uploaded an OpenAPI spec to APIClarity! 

Next up in the blog series: Reconstructing an OpenAPI Spec (for those applications that don’t already have one, which is many of them). 

Anne McCormick is a cloud architect and open-source advocate in Cisco’s Emerging Technology & Incubation organization. 

Subscribe card background
Subscribe to
the Shift!

Get emerging insights on emerging technology straight to your inbox.

Unlocking Multi-Cloud Security: Panoptica's Graph-Based Approach

Discover why security teams rely on Panoptica's graph-based technology to navigate and prioritize risks across multi-cloud landscapes, enhancing accuracy and resilience in safeguarding diverse ecosystems.

Subscribe to
the Shift
emerging insights
on emerging technology straight to your inbox.

The Shift keeps you at the forefront of cloud native modern applications, application security, generative AI, quantum computing, and other groundbreaking innovations that are shaping the future of technology.

Outshift Background