The Next-generation API Observability Platform

How do you know if a small code change can take down your site? What's really going on with your APIs? At Akita, we're building tools to help you answer that question.

Akita watches calls to web APIs in order to help you visualize your service graph, monitor your APIs, make sense of your request/response logs, and 💥 catch breaking changes 💥.

By passively watching traffic, Akita integrates in a low-friction, low-risk way, making it possible to run in CI/CD, staging, or production without too much overhead. Akita's API modeling technology to automatically catch breaking changes.

Get Started    FAQs

API Relationships

If you've ever thought it would be helpful to understand which API functions are using the same data objects, then this feature is for you.

Many APIs use IDs to refer to data objects, like customer_id to indicate a particular customer or item_id to point to an item. In an OpenAPI3 spec, the type of these fields may be string or int, but they have a particular meaning. You can't pass a customer_id to a method expecting an item_id, even if they are both strings.

When learning a specification, Akita also learns which API parameters produce and consume the same data objects. We say that such parameters are related, and we mark them with an x-akita-related OpenAPI3 annotation.

How does it work?

Akita uses several heuristics to infer parameters that produce or consume the same data type, but it hinges on tracking data objects in motion: The same value witnessed in different API calls implies that they operate on the same data type.

However, sometimes different data objects are encoded using the same value, such as when customer_id is 1 and item_id is also 1. In these cases, Akita's heuristics sometimes cannot distinguish between the two different data types, and they are assigned the same type.

Example of Relationships

Let's say you have an API with a create_folder endpoint that, predictably, creates a folder. Now, what can you do with your new folder? To know this, you need to know what other API endpoints take folder names as arguments.

On the other hand, suppose you want to create a new user, and the create_user API requires a default_folder argument. Where do you get a folder? You need to know which API calls return references to folders.

/create_folder:
    parameters:
      - $ref: "#/components/parameters/AuthorizationHeader"
    post:
      operationId: POST /api/create_folder
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - name
              properties:
                name:
                  type: string
                  x-akita-related: Type_1
        required: true
      responses:
        "200":
          description: OK response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  name:
                    type: string
                    x-akita-related: Type_1

  /api/create_user:
    post:
      operationId: POST /api/create_user
      requestBody:
        content:
          application/json:
            schema:
              properties:
                default_folder:
                  type: string
                  x-akita-related: Type_1

The x-akita-related annotation highlights the API methods that produce and consume the same data objects. In the code listing above, the name parameter in the request and response of create_folder is tagged with Type_1, showing that the folder name is supplied by the user and used to reference the newly-created folder.

Similarly, the default_folder parameter of create_user is also tagged with Type_1. In other words, create_folder creates a data object that can be used by create_user.

This may seem obvious in an example with only two API methods, but in an API with tens or hundreds of methods, understanding the relationships between different requests and responses is much more challenging.

📘

User-provided vs. machine-generated IDs

In this example, the user supplies the name of the folder to be created, and so Akita observes that the name provided is related to the name returned.

If create_folder had instead returned a randomly-generated name (e.g. create_tmp_folder), Akita would still learn that the folder name generated by create_tmp_folder is related to the input of get_folder_metadata.

Updated 10 months ago


API Relationships


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.