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.
# 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
Head over to the Akita UI, log in, and click "New Service" in the left menu.
Name it "akibox".
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.
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.
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.
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.
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.
akibox-tutorial/main.py, uncomment lines 128--134. This will add a new endpoint to the service, which allows for deleting files.
akibox-tutorial/test.sh, uncomment lines 54--60. This adds tests for the new endpoint.
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 49, remove the leading
+1- prefix in the phone number. The new phone number should be
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.
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!
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
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
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 2 months ago
|Watch Traffic to an API You Run|
|Watch Traffic to an API You Don't Run|
|Run Akita on Every Pull Request|