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 specification, or OpenAPI Spec, based on observed API traffic for an application. To recap, an OpenAPI spec compares 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 to be observed. Without API traffic, APIClarity cannot reconstruct an OpenAPI spec. 

OpenAPI specifications: Behind the scenes 

Throughout the APIClarity blog series, we’ve been using Sock Shop as our sample microservice application. See the APIClarity 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 catalog 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 catalog application, and let APIClarity reconstruct it. 

Reconstruct the spec from the API inventory tab

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

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). 

After the API Inventory screen, move to the next screen and select the Reconstructed tab (circled in green in Figure 3) to see the API endpoints for the application reconstructed by APIClarity from observed traffic.

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

Updating the parameter names

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. 

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

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

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

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). 

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). 

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

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

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

We’ll now see the listing of approved API endpoints for the catalog application. This is similar to what we saw for the upload API spec example in the prior blog, but with a notable difference. Here, only two catalog API endpoints are listed, whereas in the uploaded API spec example, four were listed. This highlights 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). 

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

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

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

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

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

Download the OpenAPI specification

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). 

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, now Outshift by Cisco.