Customize Endpoints

Akita has automatic inference algorithms that parse your incoming API and then display your API endpoints as a path with inferred arguments.

But you know your API better than we do, so it is also possible to customize your endpoints' path and arguments from the Akita console. In the console you can:

1. Collapse multiples of the same endpoint or arguments of a similar type into one endpoint, and
   1. customize the parameter name, or
   2. exclude values from the collapsed endpoint.
2. Name or rename path arguments to be more descriptive or helpful.
3. Separate out endpoints that have been collapsed into a single endpoint.

🚧

Customizations apply ONLY to new traffic

Akita builds your API model based on the behavior we see from your API. When you customize your endpoints, the customizations apply to all new behavior seen from the moment it is implemented, but it is not backported to apply to the endpoints already captured.

Before customization was possible from the Endpoint Details screen, Akita used path hints to enable customization of your endpoints. This feature is still available and you can read more about it below.

Collapsing Endpoints

If you have multiple endpoints showing up that are really iterations of a single endpoint, you can collapse the iterations to a single endpoint for a specific host. For example, if Akita is showing you /post/post-id-1, /post/post-id-2, /post/post-id-3, and /post/post-id-4, you can change the endpoint to /post/{postID} to collapse those paths for all new traffic Akita observes. Adding this customization causes any path beginning with /post/... to be collapsed going forward.

Or, if your API mixes concrete paths with parameterized paths, the Akita path inference engine will split them all out for you. If you only want to see a single path, you can indicate a split so that you only see the information you want. For example, if your API has these paths: /post/modify, /post/delete, /post/post-id-1, /post/post-id-2, ..., then you could add the annotation /post/{post_id} which would group post/modify and /post/delete into /post/{post_id}. Adding this customization causes any path beginning with /post/... to be combined and renamed going forward.

To start, navigate to the API Model tab and click the edit button.

Select the endpoints that you would like to collapse from the endpoints list. All selected endpoint must have the same host and and count of path parts.

Next, click the Collapse button to open a pre-submit window.

From this window, you can see the list of selected endpoints to be collapsed and a preview of the collapsed result.

Customizing collapsed parameter names

Before submission, you can choose to edit the collapsed endpoint's parameter names by clicking the pencil icon next to the parameter name you would like to change.

After inputting your preferred name, press the Enter key to update the name.

The new parameter name will be reflected in the collapsed endpoint result.

Excluding values from collapsed path parameters

To avoid rolling special values into the new collapsed endpoint's path parameters, you can specify values to exclude under each parameters respective excluded values list.

By default, Akita suggests values to exclude based upon your API model and previous path parameter settings.

Name path arguments

The Akita inference algorithm will display arguments as {arg}. If you want to display what the argument is or does, you need to rename {arg} to something more descriptive and helpful to you and your team.

For example, if Akita parses your API as /post/{arg} you can add an annotation /post/{postID} and {arg} will be replaced by {postID} for all new behavior that Akita observes. Adding this hint causes any path beginning with /post/{arg}/... to be renamed going forward.

To rename an argument, click on the endpoint you want to edit:

This will open the Endpoint Details screen. Click the "Rename" button in the Path Parameters section:

Then update the field name argument you wish to change and click "Save".

Separate paths

If you find an endpoint that is over-collapsed and you would like to separate out the endpoints being combined, you need to create a path hint. You will use a “^” in /post/^to require that the segment not be a path parameter; in other words, instead of combining everything under /post/ into a single displayed endpoint, we will show the paths within /post/ as separate endpoints.

For example, /post/^ will separate out /post/edit and /post/share from /post/{arg}, and ensure that they do not get collapsed.

You will need to apply a hint per host.

There are two ways to create a path hint: you can choose "Settings" from the Endpoint Details screen and then "Path inference is too aggressive" under Fix this endpoint, or you can click the gear icon on the API Model page.

To split an endpoint, find the endpoint being collapsed in the list of path hints. In this case, we're looking for /post/{postID}:

Then replace the collapsing {postID} with the ^ to split:

Path Hints

It is possible to combine, collapse, and rename endpoints entirely in path hints. In fact, that is what editing in the UI does behind the scenes! You can read how to write these path hints here.

But there's also a reason we replaced manual path hints with UI-based editing, which is that path hints require some thinking about how you write and order them. Below you will find information about:

• How path hints get applied
• How to combine path hints
• How to order path hints, and
• Examples of path hints

🚧

Customizations apply ONLY to new traffic

Akita builds your API model based on the behavior we see from your API. When you customize your endpoints, the customizations apply to all new behavior seen from the moment it is implemented, but it is not backported to apply to the endpoints already captured.

How Path Hints Get Applied

Depending on the needs of your code and your team, you might end up needing to have a lot of path hints. There are some tips and tricks to how path hints work that will help you if you have multiple hints.

Combining Path Hints

It is possible to combine path hints, however you must take care to specify them from most specific to least specific.

Taking examples from above, if your model has the paths: /post/{arg}/post-id-1, /post/{arg}/post-id-2, /post/{arg}/post-id-3, and you add a path parameter /post/{arg}/{post_id}, you will collapse the paths to the single /post/{arg}/{post_id}. You could also then rename /post/{arg}/ to /post/{post_id} and all you will see is /post/{post_id}/{post_id}.

Path hints are ‘prefix match’, and the hint /post/{postID} will match a longer path like /post/post-id-1/edit and collapse it into /post/{postID}/edit.

Ordering Path Hints

The Akita path inference engine applies path hints in order of priority. You must list more specific path hints first.

A URL matches on the first path hint that applies—and at most one path hint. For example, if you have a hint /post/{postID} and then another one on /post/{postID}/project/{projectID}, the /post/{postID}/project/{projectID} hint will never get used. If you want to use both, switch the order.

🚧

Path hints apply to future traffic only

Path hints apply to all future traffic analysis, and only to future traffic analysis.

Examples