Get Started with Akita

Welcome to the Akita Software developer hub. You'll find comprehensive guides and documentation to help you start working with Akita Software as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started

Try Akita with a Toy System

To help users get to know Akita better, we've built Akibox, a toy Dropbox-like file service. You can use it to try out Akita's spec generation to learn the Akibox API, and then make some changes to the Akibox code to see how Akita uses semantic diffing to highlight how code changes impact the API.

Step 1: Get Akibox and Fire It Up 🔥

# Clone the repo
git clone https://github.com/akitasoftware/akibox-tutorial.git
cd akibox-tutorial

# Create a python virtual environment and install dependencies
python3 -m venv venv
source ./venv/bin/activate
pip install -r requirements.txt

# Start the Akibox service
uvicorn main:app --reload

Step 2: Log into the Akita UI and Create an Akibox Service

Head over to the Akita UI, log in, and click "New Service" in the left menu.

Name it "akibox".

Step 3: Generate an API Model

Now that Akibox is running, set the Akita Client to start capturing packets in another window.

sudo akita learn --port 8000 --out akita://akibox:spec:AkiboxSpec

In a third window, run the akibox tests to generate some traffic to the service.

cd akibox-tutorial
./test.sh

Finally, head back to the window running the Akita Client (Shell 2), and hit ctrl-c to end packet capture. You should see a link printed in the CLI to see your fancy new API model.

Step 4: Get to Know Your API

Either grab the link from Step 3, or head over to the Akita UI, click "akibox" in the Services list in the left menu, and click the "AkiboxSpec" link.

At this point, you'll see a summary of your API. It should look something like this.

Look at Your API summary

The top bits summarize the number of requests that went into making this API model, the number of endpoints discovered after collapsing path arguments, and the kinds of sensitive data formats observed in the requests.

Look at the Full Details of an Endpoint

Below the summary, you can see a list of the endpoints that make up your spec. Click on an endpoint to drill down and see the shapes of requests and responses, including field names, types, and data formats.

Get to Know Akita Diffs

Akita creates semantic diffs that reflect how code changes impact your API. Let's make some changes to Akibox and see how they show up in a diff.

Change 1: Add an Endpoint

In akibox-tutorial/main.py, uncomment lines 110--116. This will add a new endpoint to the service, which allows for deleting files.

Next, in akibox-tutorial/test.sh, uncomment lines 40--46. This adds tests for the new endpoint.

Change 2: Change a Data Format

Akita can detect changes to data formats, even if no endpoints or fields are added or removed. This can happen when serialization code changes, when validation requirements are changed, or simply when validation requirements are too lax and allow unexpected data formats to pass through a service.

To simulate a data format change, we're going to change the format of hard-coded user data. Open up akibox-tutorial/main.py again, and on line 35, remove the leading +1- prefix in the phone number. The new phone number should be 323-867-5309.

Generate Another API Model

Follow Steps 1 -- 3 above to restart Akibox and create another API model, but pick a different name for the second one.

Next, head to Akita UI and click the "akibox" service in the left menu. You should see both your models listed here.

Click the "Diff" button above the table of API models, check the boxes next to your two models, and click the "Select 2 Specs" button. You should see something like this.

New endpoints are listed in green, deleted endpoints in red, and changed endpoints in yellow. You can drill down into each endpoint to see exactly what changed.

Next Steps

Akita can detect other kinds of changes, like adding or removing fields in an endpoint's request or response, adding, changing, or removing data formats, or adding or removing entire endpoints. Play around with akibox to make some more changes!

Customize Your API Models

As you're experimenting, you might find that Akita sometimes leaves path arguments in paths in the spec, e.g. /users/abc-defg-xyh instead of /users/{arg1}.

This happens when Akita doesn't have enough examples to generalize path parameters. One easy way to fix this is to add more tests! Hit the same endpoint with two different path arguments, and path parameter inference should kick in.

If that doesn't work (or you don't want to write more tests), you can also tell Akita directly which parts of a path should be path parameters. Check out the --path-parameters flag in the apispec command.

Integrate with GitHub

If you like semantic diffs, maybe you'd like to see them directly in GitHub! Check out the Integrate with GitHub page to see how to run Akita in continuous integration. You'll be able to see any differences every PR makes to your API as a GitHub comment.

Updated 15 days ago



Try Akita with a Toy System


Suggested Edits are limited on API Reference Pages

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