Skip to main content
APIContext
Talk to salesStart free
Start HereGuidesConceptsCLIReferenceChangelogStatus

Catalog

The Catalog function allows you to generate an API Key that will integrate into your application and allow us to view live monitors, as well as all your current monitors, and show these in your Catalog. From here, you can add any of these monitors to your Monitor List and add them to schedules or workflows. Additionally, you can upload your OAS specification to compare to the live traffic for any inconsistencies between the intended architecture and the implemented architecture.

Configure Catalog​

Set up an API Key​

The Catalog can be found under the Analytics & Reporting section in the sidebar.

Sidebar with Catalog highlighted under the Analytics and Reporting section

From the Catalog, you can now create your API Key and upload your specifications. To create your API Key, select the Create an API Key button.

Inventory page with the Generate my API key button highlighted

A popup will appear with your new API Key that you can copy to your clipboard.

Popup showing the new API key with a copy-to-clipboard button

If you lose your API Key, it can also be found under the Advanced section in APImetrics API. From there it can also be deleted.

Integrate With Your Application​

APImetrics has multiple observability and egress adaptors for integration with your application. You can view our observability adaptors.

Optional: Upload OpenAPI Specification​

To upload your file, select the Upload my JSON or YAML file button.

Add an OpenAPI spec card with the Upload my JSON or YAML file button highlighted

This will open a popup where you can upload your file by selecting the Choose File and then the Upload File buttons. Note that specification files are limited to 8 MB each.

Upload an OpenAPI Specification popup highlighting the Choose file and Upload file buttons

After the upload, confirm which base URLs to use for the spec: the specification's dialog lists them under Servers ("Please confirm which base URLs you wish to use for this OpenAPI specification"). Only these URLs are used to match monitors, as described in How monitors are matched to your spec.

Checks on an uploaded spec​

Every uploaded spec is linted. A spec that is not OpenAPI 3.x, or that cannot be parsed, is converted to OpenAPI 3.0 and then linted again.

These rules report errors: spec, path-declaration-must-exist, no-identical-paths, and no-unresolved-refs. Because of no-unresolved-refs, every $ref must resolve within the uploaded file.

These rules report warnings: spec-strict-refs, no-undefined-server-variable, path-not-include-query, path-parameters-defined, operation-operationId-unique, operation-parameters-unique, operation-2xx-response, spec-components-invalid-map-name, no-server-example.com, no-server-trailing-slash, no-ambiguous-paths, and no-enum-type-mismatch. A spec with no openapi field, such as a Swagger 2.0 file, also gets the warning "API specification file should be OpenAPI 3.x".

Investigating Results​

Once you've configured your Catalog, you can then explore your results. From here, you can see the HTTP Method, the endpoint URL, the Source of the call, and how many times it has been called. The Source is useful for telling you what monitors are and are not identified in your specs. All of your monitors will be aggregated in the Catalog for easy analysis. From here, you can also add any monitors that are unmonitored by APImetrics by clicking the Monitor this Endpoint button.

Catalog results table listing endpoints by HTTP method, URL, source, and API call count with Monitor this Endpoint buttons

How monitors are matched to your spec​

The Catalog lists each operation in your spec once for each confirmed base URL that applies to it, as a method and a full URL (the base URL followed by the operation's path). Server variables in a base URL are expanded: each value of an enum, or the default. A monitor appears against an operation when the two match:

  • Method. The HTTP methods must be the same.
  • Path, compared from the end. The URLs are compared one path segment at a time, starting from the last segment. Query strings are ignored.
  • Path variables match any segment. A variable in the spec, such as {petId} in /pets/{petId}, matches any single segment, so a monitor that calls /pets/123 matches it.
  • Hosts must agree when both have one. If both URLs include a host, the scheme and host must be the same.
  • A shorter URL can match the end of a longer one. For example, an operation whose base URL is the relative path /v1 matches a monitor that calls https://api.example.com/v1/pets for /v1/pets.

A monitor that matches no operation is still listed, but not as part of your spec.