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 💥.

Akita is 1) blackbox, 2) runs in CI/CD, staging, or production, and 3) uses API modeling technology to automatically catch regressions.

Get Started    FAQs

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.

--traces

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.

--out

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

Flag

Description

Default

--format [yaml | json]

Determines the output format of the spec.

yaml

--tags "key1=val1,key2=val2"

Adds tags to the spec.

--include-trackers

If present, then requests to third-party trackers are included in the spec.

By default, requests from third-party trackers are removed.

--infer-field-relations

If 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.

Flag

Description

--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.

Flag

Description

--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 Endpoint

Final Endpoint

/v1/users/usr_1

/v1/users/{user}

/v1/users/usr_2/team

/v1/users/{user}/team

/v1/users/{arg3}

/v1/users/{user}

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 Endpoint

Final Endpoint

/v1/users/usr_1

/v1/users/{user}

/v1/users/usr_2/projects/awesome_project

/v1/users/{user}/projects/{project}

/v1/users/usr_3/teams/team_1

/v1/users/{user}/teams/team_1

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 Endpoint

Final Endpoints

/v1/{arg2}

/v1/users
/v1/projects

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.

Flag

Description

--github-branch

Name of the GitHub branch this spec belongs to.

--github-commit

SHA of the GitHub commit that this spec was generated from.

--github-pr

GitHub PR number that this spec belongs to.

--github-repo

Name 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.

Updated 3 months ago


apispec


Suggested Edits are limited on API Reference Pages

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