API Discovery

API discovery rules consist of API documentation, naming, and exclusion rules. Using these components, you can:

• Upload documentation for use while starting a conformance analysis or creating an AST suite.

• Create rules for managing the number of APIs being monitored.

• Create rules for naming APIs better.

While the uploaded documentation is visible across the Traceable platform, the naming and exclusion rules apply to all future API requests if enabled. However, you must have reasonable knowledge of regular expressions to create meaningful rules. You can use websites like regex101 to view and learn regular expressions. After configuring the rules, the API Catalog displays the APIs based on these rules.

API documentation

API documentation refers to the specifications you use for testing and analysis. You can upload the documentation and use it in Conformance Analysis or API Security Testing (AST) Suites according to your requirements. Traceable supports the following types of API documentation:

• Open API Spec

• Postman Collection

• Postman Environment

• GraphQL Schema

You can use either of the above types and upload their corresponding files while creating API documentation. To create an API documentation, navigate to Settings () → API Catalog → API Discovery → API Documentation tab, click + Upload API Documentation, and complete the following steps:

1. Specify the API Documentation Name. For example, OpenAPI doc for mismatch.

2. Select the API Documentation Type from the drop-down list. For example, OpenAPI Spec.

3. Upload the documentation file.

4. Click the toggle under Enabled for Naming to allow Traceable to rename API endpoints according to the specification.

5. Click Save.

Traceable shows the uploaded documentation in the API Documentation tab.

API naming

API naming rules are helpful in situations when you wish to exclude certain portions from the Traceable provided API names. You can also create a rule to give an entirely different name to the discovered API. However, you should have reasonable knowledge of regular expressions to match the exact URI patterns and create a new API name. You can apply the naming rule to all environments or one or more environments and their specific services. To create a naming rule, navigate to Settings () → API Discovery → API Naming tab and click + Create Naming Rule. Creating a naming rule consists of the following steps:

1. Rule Creation

2. Request Matching

3. API Endpoint Naming

In the below steps, we consider that the API named by Traceable is _order/health/traceable__cart__test__tags__123456__0 and you wish to rename it to order/health/tags.

Step 1 — Rule creation

Complete the following steps to create a rule:

1. Specify a name for the rule. For example, Health API.

2. Click the toggle corresponding to the rule name to enable or disable the rule.
   You can also enable or disable it at any time post-creation. By default, all rules are enabled.

Step 2 — Request matching

Complete the following steps to set up the criteria for the rule:

1. Select the Environment where you want to apply the rule. For example, All.
   By default, all environments are selected.

2. Select the Service where you want to apply the rule. For example, All.
   By default, all services are selected.

3. In the HTTP Path Regex Pattern field, specify the regex pattern Traceable should match. For example, _order/health/.+___(.+)___.+___0.

4. Click Show Preview.

Traceable shows a preview of all the URIs that have the word match as per the specified regex pattern in the Preview Pane. In the example above, the match is for URIs in the last 1 day. You can change the period to 6 or 12 hours to see all the matching URIs. However, if you want better match results, specify a more fine-tuned regular expression.

Step 3 — API endpoint naming

Complete the following steps to name the API:

1. Specify the updated API name using regex grouping. For example, order/health/$1.

2. Click Show Preview.

Traceable shows a preview of all the URIs that have the word match as per the specified regex pattern, along with their new endpoint names in the Preview Pane. In the example above, the match is for URIs in the last 6 hours. You can change the time period to 12 hours or 1 day to see all the matching URIs. However, if you want better match results, specify a more fine-tuned regular expression.

If you are satisfied with the listed URIs, click Save. However, to get better match results, you must specify a more fine-tuned regular expression.

API endpoint naming examples

Following are a few examples of API naming that you can use or modify according to your requirements:

Single ID

If you have URLs like:

• orders/1Dvb0-xaLTnwYbkGxmMPq3cYdZFHkUSxIUWTGahW3aWM

• orders/1bw-G30aoMUa8XS7L6x-nAS0j4T6A_wWUCCxQqYB9xa

and you wish to rename them as orders/{orders-id}, then you should configure the rule as follows:

Regex — orders/[a-zA-Z0-9-_]+

Traceable renames the URL as orders/{orders-id}

Multiple IDs

If you have URLs like:

• users/alice/orders/1bw-G30aoMUa8XS7L6x-nAS0j4T6A_wWUCCxQqYB9xag

• users/bob/orders/1bw-G30aoMUa8XS7L6x-nAS0j4T6A_wWUCCxQqYB9xag

and you wish to rename them as users/{users-id}/orders/{orders-id}, then you should configure the rule as:

Regex — users/[a-zA-Z]+/orders/[a-zA-Z0-9-_]+

Traceable renames the URL as users/{users-id}/orders/{orders-id}

Simple Groups

If you have URLs with groups, such as:

• blogs/2014-flags-are-a-code-smell

• blogs/2012-boolean-as-primitive-argument

and you wish to rename them as:

• blogs/flags-are-a-code-smell

• blogs/boolean-as-primitive-argument

then, you should configure the rule as:

Regex — blogs/[0-9]{4}-([a-z-]+), that is, ( and ) are used to capture the groups.

Traceable renames the URL as blogs/$1. In the renamed URL, $1 points to the first captured group. Similarly, $2 captures the second group, $3 captures the third group, and so on.

Rearrange groups

If you have URLs with groups, such as:

• users/browse/products

• users/browse/catalog

• users/checkout/cart

and you wish to rearrange them as:

• users/products/browse

• users/catalog/browse

• users/cart/checkout

then, you should configure the rule as:

Regex — users/([a-z]+)/([a-z]+)

Traceable rearranges the URL as users/$2/$1

API naming exclusions

If you have numerous APIs in your API infrastructure and want to monitor only a specific number of APIs, you can create an exclusion rule to exclude an API or a set of APIs. If you have more than one rule, they are applied in the order they are listed.

To create an exclusion rule, navigate to Settings () → API Catalog → API Discovery → API Naming Exclusions tab and click + Create Exclude Rule. Creating an exclusion rule in Traceable consists of two steps:

1. Rule Creation

2. Request Matching

Step 1 — Rule creation

Complete the following steps to create a rule:

1. Specify a name for the rule. For example, “api-v2” exclusion rule.

2. Click the toggle corresponding to the rule name to enable or disable the rule.
   You can also enable or disable it at any time post-creation. By default, all rules are enabled.

Step 2 — Request matching

Complete the following steps to set up the criteria for the rule:

1. Select the Environment where you want to apply the rule. For example, HighTechApp.
   By default, all environments are selected.

2. Select the Service where you want to apply the rule. For example, open-api-gateway.
   By default, all services are selected.

3. In the HTTP Path Regex Pattern field, specify the regex pattern Traceable should match, such as api/v2.

4. Click Show Preview.

Traceable shows a preview of all the URIs that have the word match according to the specified regex pattern in the Preview Pane. Traceable does a partial match of the word, that is, it gives a match if the word appears anywhere in the URI. In the example above, the match is for URIs in the last six hours. You can change the time period to 12 hours or 1 day to see all the matching URIs. If you are satisfied with the listed URIs, click Save. However, if you want better match results, specify a more fine-tuned regular expression.