The First API-Centric 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

Watch API Traffic to a Server

Now we're going to show you how to automatically generate an API model for your REST APIs by running the Akita Client alongside your service. In just a few minutes, you'll be able to use your API model for spec generation, diffing, and more.

πŸ“˜

Private Beta

Akita is currently in private beta. If you are not part of the private beta, you will need to request an invite before continuing. Get an invite.

Before We Get Started

You'll need the following things in order to follow along with this tutorial:

  • Akita Client - If you don't already have the Akita Client installed, follow this guide to get set up.
  • API Service - You will need a service that provides an HTTP API that can be run on a host where the Akita Client can monitor network traffic. If you don't have an API service, follow this guide instead.
  • HTTP Client - You will need to make several HTTP requests to your API Service. If you don't already have tests that do this, we recommend using a tool like Postman to make this easier.

Getting Started

Now we'll show you how to use Akita to:

Create a Service

To build API models from traffic, you first need to create a β€˜Service’ to associate the model with.

You can name your new service whatever you like, but it will be easier to find it again later if the name reflects the name of the API whose behavior you're learning.

Automatically Learn an API Model

Now you're reading to start learning. All you need to do is fire up the Akita Client and exercise the target REST API. You can check out the learned endpoints as you go, or all at once in the end.

Starting Akita

To start, Akita needs to know what network traffic to monitoring and which service to associate the monitored traffic with:

  • Service Name - the name of the Service we created in the Akita Cloud.
  • Port (optional) - the port your service is listening for a connection on.

If you don't know these, you may find it helpful to read our FAQ answers about how to figure out the Docker container where your service runs and what port your service runs on.

If you are running in Docker we will also need your API Key ID, API Key Secret, and the Network your container is attached to.

With this information, you can start Akita by running the command:

akita learn --service {service name} --port {port}
sudo akita learn --service {service name}   --port {port}
# Only use this if your service is running in a Docker container!  If
# you run the Akita agent in Docker, it will only see Docker network
# traffic, not traffic on your host machine.

docker pull akitasoftware/cli:<<current_cli_version>> && docker run --rm -it \
  --env AKITA_API_KEY_ID=${KEY_ID} \
  --env AKITA_API_KEY_SECRET=${KEY_SECRET} \
  --net="container:${CONTAINER_NAME}" \
  akitasoftware/cli:<<current_cli_version>> learn \
    --service {service name} \
    --port {port}

After successfully starting the learn, you should see output that looks like this:

[INFO] Running learn mode on interface lo0
[INFO] Preview the learned API spec at https://app.akita.software/service/svc_4UxRRNmhL8R2MAqrmCmCvn/spec-preview/lrn_40lxi9tlHnfdiRsBzXYbBY
[INFO] Send SIGINT (Ctrl-C) to stop...

πŸ“˜

Why would I specify a port?

Without the --port flag, Akita will collect all the traffic going over your network interfaces. This includes outgoing traffic your service may send to its downstream dependencies (e.g. calls to Datadog APIs, Amazon Web Services, etc.), as well as other network traffic from other applications running on your machine.

Adding the --port flag will exclude any traffic not sent to or from the specified port.

Exercise the API

Once Akita is running, start making requests to your API. The Akita Client watches each request and sends a scrubbed version back to the Akita Cloud for learning an API model. You can get a sneak peek at the preview link as you go. πŸ‘€

Stopping Akita

When you are done, simply hit Ctrl-C.

^C
[INFO] Received SIGINT, generating API specification...
[INFO] Opening https://app.akita.software/service/svc_4UxRRNmhL8R2MAqrmCmCvn/spec/api_1XStTp197RbGt6N2svEh25 in the browser...

View Your API model

Head over to the Akita console to see what we learned.

Here you'll see stats about your API, like the number of requests in the trace that went into making the model, the total number of endpoints Akita discovered (after grouping requests by path parameter), anddata formats detected.

You can drill down into each endpoint to learn more about it.

Each endpoint shows the path and query parameters, headers, and body fields expected in a valid request, as well as the kinds of responses the endpoint supports.

Fields are labeled with their types (string, int, etc.) and, when possible, specific data formats, like email, date, timestamp, phone number, and so on. You can find a complete list of data formats in Supported Data Formats .

Downloading an API Specification

Akita represents API models as annotated YAML files that you can download and use anywhere OpenAPI3 specs are used. What you see in this model is also what Akita uses for semantic diffing across API models.

Troubleshooting

The Akita CLI will show an error if the collection of API traffic fails or results in an empty trace. Possible causes include:

  • Non-root users do not have the permissions to capture network traffic. You will see the message You don't have permission to capture on that device if that is the case. Try running as root, or with sudo.
  • The API traffic you are attempting to capture runs over HTTPS, instead of HTTP. In this case the API will give the error No inbound HTTP calls captured, as well as report the number of packets captured with Captured %d TCP packets total; %d unparsed TCP segments. This indicates that some network traffic was detected, but could not be successfully parsed.
  • The TCP port number you gave was incorrect, so the traffic was not included in the trace. This case will also report an error No inbound HTTP calls captured, but additionally show the explanatory message Did not capture any TCP packets matching the filter or Did not capture any TCP packets during the trace,

See the Diagnostics section in the learn command for more information.

Updated 2 months ago



Watch API Traffic to a Server


Suggested Edits are limited on API Reference Pages

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