Customize Path Parameters

Akita has automatic inference algorithms to guide parsing and displaying your API endpoints with the correct path arguments. Since every API is unique, and you know what is important to your team and product, Akita also provides path hints so make it possible to customize path parameter inference. Every API is different, and you have unique insight into what is important to your team and organization, so it is likely that you will want to customize what you see in the Akita console at some point.

🚧

Customizations apply ONLY to new traffic

Akita builds your API model based on the behavior we see from your API. When you customize your paths, 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.

You can customize your paths in the Akita console, via the "Customize Paths" tab of the API Model page.

16441644

The "Customize Paths" tab allows you to define and add path hints to Akita's path inference algorithms.

16441644

Path Hints

Path hints allow you to alter your API model so you see the information you care most about more clearly. You can:

Collapse paths

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. If you have multiple hosts with the same paths, you will need to create a separate path hint for each of them.

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 would add a hint /post/{postID} to collapse those paths for all new traffic Akita observes. Adding this hint causes any path beginning with /post/... to be collapsed going forward.

16171617

If you had the same paths on additional hosts, you would need to create a path hint for each of them.

16171617

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 create a path hint 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.

16171617

If you have the same arguments on additional hosts, you will need to create a path hint for each of them.

16171617

Combine paths

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 hint causes any path beginning with /post/... to be combined and renamed going forward.

16171617

If you have the same mix on additional hosts, you will need to create a path hint for each of them.

16171617

Separate paths

You can also 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.

As with other path hints, you will need to apply each hint per host.

16161616

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.

16181618

🚧

Path hints apply to future traffic only

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

Examples

31063106
AnnotationMatchesDisplayed as
/post/{postID}/post/post-id-1
/post/post-id-2/edit
/post/post-id-3/project/project-id
/post/{postID}
/post/{postID}/edit
/post/{postID}/project/project-id
/post/{postID}/projects/{projectID}/post/post-id-1/project/project-id/post/{postID}/project/{projectID}
/post/{postID}/^/post/post-id-1/share
/post/post-id-2/edit
/post/{postID}/share
/post/{postID}/edit

What’s Next