Published on 00/00/0000
Last updated on 00/00/0000
Published on 00/00/0000
Last updated on 00/00/0000
Share
6 min read
Published on 04/05/2023
Last updated on 02/05/2024
APIClarity: Reconstructing an OpenAPI Specification
Share
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).
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).
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 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).
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 catalogue 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 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).
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 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).
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.
Conclusion
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 to
the Shift!
Get emerging insights on emerging technology straight to your inbox.
