Deprecated command

We no longer actively support this command. We recommend you use apidump instead and integrate Akita with your active traffic.

The apispec command transforms traces into OpenAPI3 specifications annotated with additional information, like data formats.

# Creating a spec from a trace in the Akita Cloud:
akita apispec --traces akita://myService:trace:traceName \
  --out akita://myService:spec:specName

# Creating a spec from a trace stored in the local file system:
akita apispec --service myService --traces path/to/traceName.har \
  --out path/to/specTarget.yaml

Specs created in the Akita Cloud will be located in the service specified in the AkitaURI. For specs output locally, a copy will also be created in the service given in the --service flag.


Use the --traces flag to choose one or more traces to build a spec from. Each argument is either a path to a trace file in the local file system or an AkitaURI referencing a trace located in the Akita Cloud.

--trace-tag key=value

Specify a tag of the form key=value to select the most recent trace that has a matching trace. See Parallel Learning for instructions on using this option to create a model from a distributed trace.


The --out flag identifies the target location to create the spec and can be a local file path or an AkitaURI.

The special value --out - prints the spec to stdout.

By default, if --out is not present, then the spec will be assigned an auto-generated name and stored in the Akita Cloud in the service supplied in the --service flag. In this case, the --service flag is required.

Optional Flags

--format [yaml | json]Determines the output format of the spec.yaml
--from-time YYYY-MM-DD hh:mm:ss
--to-time YYYY-MM-DD hh:mm:ss
If present, only includes events observed in the given time range. If desired, the hh:mm:ss or the :ss can be omitted, in which case the start of the day or minute is used. The client's local time zone is assumed. If the given time occurs during a transition to or from daylight saving time, then one side of the transition is arbitrarily chosen.By default, all events from the specified traces are included in the spec.
--tags "key1=val1,key2=val2"Adds tags to the spec.
--include-trackersIf present, then requests that third-party trackers be included in the spec.By default, requests from third-party trackers are removed.
--infer-field-relationsIf present, adds API Relationship annotations to the spec.By default, API relationships are omitted.

Removing Unnecessary Endpoints

As you collect traffic traces and generate specs, you might find that your traces (and therefore specs) contain extra traffic not part of your API. For example, suppose your service exposes an API but also serves static resources, like images, JavaScript files, font families, and so on.

--path-exclusions REGEX[,REGEX]Comma-separated list of regular expressions. Endpoints with paths that match at least one regular expression are omitted from the spec.

You can use the --path-exclusions flag to avoid including these requests in your spec. Continuing with the example, here's how you would omit JPEG, PNG, and JavaScript files.

akita apispec --traces akita://myService:trace:myTrace \
  --out akita://myService:spec:prunedSpec \
  --path-exclusions '*.jpg,*.png,*.js'

Adding and Removing Path Parameters

Akita automatically infers path parameters based on API traffic. For example, a trace might contain two requests with two different user IDs in the path.

# Requests
GET /api/v1/users/usr_134819/friends
GET /api/v1/users/usr_999999/friends

# Inferred Endpoint
GET /api/v1/users/{arg4}/friends

However, sometimes Akita gets it wrong. In that case, you can force specific positions in paths to be (or not to be) path parameters.


Likely Cause of Missing Path Parameters: Too Few Requests

Akita infers path parameters by comparing similar requests. In the example above, only the User ID differed in the path, and the shapes of the requests and responses are similar, making it likely that the User ID segment is a path parameter.

However, if Akita only sees one request to an endpoint, it won't have enough information to generalize path parameters.

--path-parameters PATHPREFIX[,PATHPREFIX]List of path prefixes. See below for an explanation of path prefix patterns.

A path prefix pattern identifies one or more positions in a path as having (or not having) a path parameter. Paths, in this case, are made up of path segments separated by /.

In a path prefix pattern, each segment is either a string, a path parameter ({parameter_name}), or a placeholder ^ that indicates that the segment should not be generalized into a path parameter.

Here are a few examples.

Example 1: Simple Prefix Match

--path-parameters /v1/users/{user}

Inferred EndpointFinal Endpoint

Example 2: Longest Prefix Match

When you add more than one prefix pattern, the longest prefix match gets applied.

--path-parameters /v1/users/{user},/v1/users/{user}/projects/{project}

Inferred EndpointFinal Endpoint

Example 3: Removing a Path Parameter

Sometimes, Akita infers a path parameter where none exists. As a result, different paths are incorrectly collapsed into the same endpoint. The ^ character indicates that a given segment should not be a path parameter.

--path-parameters /v1/^

Inferred EndpointFinal Endpoints

GitHub and CI Integration

When adding Akita to a CI/CD pipeline, you will need to indicate the GitHub branch, commit hash, pull request number, and repository name. This lets Akita publish a GitHub comment to your PR summarizing any API differences introduced by the PR.


CircleCI and Travis

If you use CircleCI or Travis for continuous integration, Akita's apispec command will automatically detect the relevant GitHub info from your environment. No need to use the --github-* flags.

--github-branchName of the GitHub branch this spec belongs to.
--github-commitSHA of the GitHub commit that this spec was generated from.
--github-prGitHub PR number that this spec belongs to.
--github-repoName of the GitHub repo (of the form <repo_owner>/<repo_name>) containing the associated branch/commit/PR.

When using these flags as part of CI to trigger a GitHub commit message, all flags are required.