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
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.
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
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.
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
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.
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
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.
create_folderhad instead returned a randomly-generated name (e.g.
create_tmp_folder), Akita would still learn that the folder name generated by
create_tmp_folderis related to the input of
Updated 10 months ago