Outshift Logo


6 min read

Blog thumbnail
Published on 04/05/2023
Last updated on 03/21/2024

APIClarity: Reconstructing an OpenAPI Specification



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

Reconstructing an OpenAPI Specification

In this blog, I’ll show you how APIClarity can reconstruct an OpenAPI spec based on observed API traffic for an application. To recap, an OpenAPI spec is used to compare incoming API traffic against what’s expected and allowed. An OpenAPI spec can either be uploaded, or APIClarity can reconstruct one, which is what we’ll cover here. 

Note that API traffic has to be flowing for your application in order to be observed. Without API traffic, APIClarity cannot reconstruct an OpenAPI spec. 

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.

In a previous blog, we went through the steps of uploading an OpenAPI spec for the catalogue microservice in the Sock Shop demo application. For our purposes here, let’s pretend like the OpenAPI spec doesn’t exist yet for the Sock Shop catalogue application, and let APIClarity reconstruct it. 

Reconstruct the Spec 

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

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, select the Reconstructed tab (circled in green in Figure 3) to see the API endpoints for the application that were reconstructed by APIClarity from observed traffic.

Reconstructed Tab
Figure 3: Choose Reconstructed Tab

Reconstructed OpenAPI specs need to be reviewed and approved by the user before they can be used for comparison with incoming traffic. On the next screen, click "Review" to see the observed API endpoints (see Figure 4). 

Click “Review” to see Reconstructed APIs
Figure 4: Click "Review" to see Reconstructed APIs

Next, you’ll see a listing of the various API endpoints that were observed. Note that the API parameter names are generic (e.g. “param1” in Figure 5). Let’s fix that. 

Observed API Endpoints
Figure 5: Observed API Endpoints

Click on the endpoint with the generic parameter name, and then the "Update Parameter Name" pulldown (Figure 6).

Update Parameter Name
Figure 6: Update Parameter Name

We know that the parameter in this case is a catalogue ID, so let’s change the name to “id” (Figure 7). 

Change “param1” to “id”
Figure 7: Change "param1" to "id"

Now, in the Spec Reviewer window, we’ll see the updated parameter name (Figure 8).

Updated Parameter Name (“id”)
Figure 8: Updated Parameter Name ("id")

Now that the API endpoints are updated, let’s approve them. Click the arrow next to "Path" to select all endpoints, then select Approve Review (both circled in green in Figure 9). 

Select all Endpoints then Click Approve Review
Figure 9: Select all Endpoints then Click Approve Review

An Approve Review window will pop up asking us to approve the review and select the OAS (OpenAPI spec) version. Click the down arrow (Figure 10). 

Click Down Arrow on Approve Review UI
Figure 10: Click Down Arrow on Approve Review UI

You’ll see OAS v2 and v3 as choices. Let’s go with the latest and greatest. Choose OAS V3 (Figure 11).

Choose OAS V3
Figure 11: Choose OAS V3

Click Yes to approve the OpenAPI V3 spec version of this API (Figure 12). 

Click Yes button to Generate Reconstructed Spec
Figure 12: Click Yes button to Generate Reconstructed Spec

Now that the reconstructed spec is approved, we’ll see the API inventory listing in the APIClarity UI. Click on “default-tag” (Figure 13). 

Click “default-tag”
Figure 13: Click "default-tag"

We’ll now see the listing of approved API endpoints for the catalogue application. This is very similar to what we saw for the upload API spec example in the prior blog, but with a notable difference. Here, only two catalogue API endpoints are listed, whereas in the uploaded API spec example, four were listed. This is highlighting a limitation of the spec reconstruction process – APIClarity can only include APIs that were observed. If some APIs (in this case two of them) were never called, APIClarity would not know about them, and thus would not include them in the reconstructed spec. After the reconstructed spec is approved, if those two missing APIs were called, they would be reported as shadow APIs (i.e. undocumented API calls). They could then be added to the approved spec if desired. We’ll cover shadow APIs in a future blog. 

Click the arrow next to one of the endpoints (Figure 14). 

Browse Reconstructed API Endpoints
Figure 14: Browse Reconstructed API Endpoints

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

API Endpoint “Hit Count”
Figure 15: API Endpoint "Hit Count"

To see the API spec in Swagger, click on "see on Swagger" (circled in green in Figure 16).

Click see on Swagger
Figure 16: Click "see on Swagger"

Each API endpoint is listed in Swagger (Figure 17).  

Swagger UI Listing API Endpoints
Figure 17: Swagger UI Listing API Endpoints

Click on each endpoint to see example request parameters and an example response. 

Swagger UI API Endpoint Parameters
Figure 18: Swagger UI API Endpoint Parameters

At the bottom, in the Schemas pane, each API response schema is provided. 

Swagger UI Schemas Detail
Figure 19: Swagger UI Schemas Detail

Download the Spec 

Now that we have an approved OpenAPI spec for our application, we can download it. On the Swagger UI, up at the top, there’s a link to download a JSON file for the reconstructed OpenAPI spec (circled in green in Figure 20). 

Link to Reconstructed Spec in Swagger UI
Figure 20: Link to Reconstructed Spec in Swagger UI

Spec Differences 

Similar to how spec differences can be detected between observed API traffic and an uploaded OpenAPI spec, they can also be detected with a reconstructed/approved spec. See here for an example spec difference that was flagged. 


Congrats, you have now reconstructed an OpenAPI spec with APIClarity! 

Next up in the blog series: Detecting Shadow APIs. 

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.

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