- 27 Jun 2024
- 5 Minutes to read
- Print
- PDF
API Discovery
- Updated on 27 Jun 2024
- 5 Minutes to read
- Print
- PDF
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:
Specify the API Documentation Name. For example, OpenAPI doc for mismatch.
Select the API Documentation Type from the drop-down list. For example, OpenAPI Spec.
Upload the documentation file.
Click the toggle under Enabled for Naming to allow Traceable to rename API endpoints according to the specification.
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:
Rule Creation
Request Matching
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:
Specify a name for the rule. For example, Health API.
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:
Select the Environment where you want to apply the rule. For example, All.
By default, all environments are selected.Select the Service where you want to apply the rule. For example, All.
By default, all services are selected.In the HTTP Path Regex Pattern field, specify the regex pattern Traceable should match. For example,
_order/health/.+___(.+)___.+___0
.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:
Specify the updated API name using regex grouping. For example,
order/health/$1
.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.
Note
The number of segments in the Request Matching and API Endpoint Naming sections should be the same. For example, as shown above, there are three segments in Request Matching (Step 2) and API Endpoint Naming (Step 3).
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:
Rule Creation
Request Matching
Step 1 — Rule creation
Complete the following steps to create a rule:
Specify a name for the rule. For example, “api-v2” exclusion rule.
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:
Select the Environment where you want to apply the rule. For example, HighTechApp.
By default, all environments are selected.Select the Service where you want to apply the rule. For example, open-api-gateway.
By default, all services are selected.In the HTTP Path Regex Pattern field, specify the regex pattern Traceable should match, such as api/v2.
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.