API Documentation and Inspector

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 Specification

• Postman Collection

• Postman Environment

• GraphQL Schema

You can use either of the above types and upload one or more files according to your requirements. For more information on uploading files, see Uploading API Documentation.

For the OpenAPI specification documentation type, Traceable also provides the option to enable:

• API naming — This option is useful when you want Traceable to use the specification for API naming.

• API Inspector — This option is useful when you want Traceable to run the specification analyzer on your uploaded files.

• API Discovery —  This option is useful when you want Traceable to discover APIs from the uploaded specification.

These options are available while uploading API documentation. For more information on the steps to do this, see the section below.

Uploading API Documentation

Navigate to API Catalog → API Documentation tab, and click Upload in the page’s top right corner to start uploading an API documentation. The following demo shows how you can upload a documentation while the below list provides a description of each field during this process.

As part of uploading the documentation, complete the following:

• API Documentation Name — The name of the API documentation. This field is non-editable as Traceable uses the uploaded specification name as the documentation name.

• API Documentation Type — The type of API documentation you wish to upload. For example, Open API Spec.

• Enabled for Naming — The toggle, if enabled, allows Traceable to rename API endpoints according to the uploaded specification. For more information on API naming rules, see API naming.

  Note

  This option is only available for Open API Spec documentation types.

• Run API Inspector — The toggle, if enabled, allows Traceable to analyze the uploaded specification for security concerns. For more information, see API Inspector.

  Note

  This option is only available for Open API Spec documentation types.

• Enable API Discovery — The toggle, if enabled, allows discovery of APIs based on the specification(s) you upload. Traceable lists the discovered APIs on the Inventory page with OpenAPI Specification (OAS) as the source. For more information on these APIs, see API Endpoints.

  Note

  This option is only available for OpenAPI Spec documentation types.

• Upload Spec(s) — The API documentation that you wish to upload. You can upload a single file or a folder containing multiple files. Post-upload, you can update the file name and path according to your requirements.

  Note

  When uploading a folder, you must ensure that all files are present in a single folder so that Traceable can understand the references (connections) between files. For more information, see API Referencing.

  Traceable uses this file name as the API documentation name. Following is the folder structure used in the above demo:
  
  

Once you have configured the above, click Save. Traceable displays the uploaded documentation as shown in the image below.

You can click on an API documentation to view the following under it:

• Reference Tree — The main specification file (parent specification) from the directory or folder you upload may contain one or more references, either nested or standalone. The tree is a visual representation of these references and helps you navigate the connections between them. For example, in the above image, openapi.yaml is the main specification above and contains references to orders.yaml, customers.yaml, and products.yaml files. Similarly, orders.yaml and customers.yaml contain references to customers.yaml and address.yaml files respectively, while products.yaml does not contain any references.
  The reference tree visually shows how different API specifications link together. This makes it easy to see the structure and resolve missing references quickly. For more information, see API Referencing.

• API Spec — This section shows the API specification in detail. This is the resolved API specification, meaning that Traceable resolves all references across the files that you uploaded. For example, the openapi.yaml file shown above contains references to orders.yaml, customers.yaml, and products.yaml files. However, those references are not visible in the above image as Traceable replaced those references with the content present in the files.

• Paths found in OpenAPI spec — This section lists all the paths Traceable discovers as part of the uploaded OpenAPI specification. If you enabled the API inspector while uploading the document, the section shows the issues found and the API inspector score corresponding to each path. For example, in the above image, the /v1/customers/{customerid} path contains 3 issues and an API inspector score of 68. Similarly, this information is shown for all paths within an API documentation. For more information on the issues and score, see API Inspector.

API Referencing

If you upload a directory or multiple specifications, Traceable goes through the main specification file (parent spec) and searches for references ($ref). Based on the files you upload, Traceable resolves the paths with their respective files. Based on these references, Traceable creates a reference tree which is visible when you edit any existing documentation or in the documentation detailed view as shown below.

Note

• While uploading the files, you must ensure that the files are structured under a single directory such that Traceable can identify the specification’s location.

• API referencing is only available for the Open API Spec documentation type.

Traceable highlights the unresolved references with a red dot at the top right of the file or folder on the API Documentation page, for example, paths.yaml folder in the above image. This mainly occurs when the file is missing. At that time, you can edit the API document and do either of the following in the Reference Tree section:

• Click the Upload icon and upload the missing documentation.

• Click on the missing document field and select an existing one from the drop-down.

  Note

  If you select from the existing specifications, Traceable moves that file to the path mentioned in the main specification (parent specification) file.

Traceable tries to resolve the references based on the above documents. If it is unable to do so because of some issues in the documents, you can repeat the above step.

API Inspector

The API Inspector is a code analyzer of the Open API documentation that you upload. If you enable this feature, Traceable goes through the documentation and produces a result at the path level. Traceable performs these checks once a day, and as soon as you update or upload the API documentation.

Note

The API Inspector feature is only available for the Open API Spec documentation type.

The API inspector checks for issues in three areas:

• Security — This category checks for potential security issues, such as weak authentication mechanisms, missing headers, accurate references, etc that can expose APIs to attacks.

• Format — This category checks whether the API paths conform to the expected structure and formatting rules as specified in the OpenAPI document, ensuring proper syntax and compliance with API standards.

• Data Validation — This category checks whether the data types and structures defined in the OpenAPI document are properly implemented, ensuring that inputs and outputs match the expected formats, constraints, and value ranges.

Each of the above categories has multiple checks associated with it. Traceable provides these checks out-of-the-box and executes them on each path present in the OpenAPI specification and calculates an API Inspector score. The score is calculated for each path and as a whole for the uploaded API documentation. The audit score ranges from 0-100, with 100 being the highest. A higher score represents a better compliance.

Traceable also shows the following detailed information for each path. To view this information, navigate to the detailed view page of an API documentation, Paths found in OpenAPI spec section, and click on a path.

• API Inspector score for that path

• The list of checks performed on that path, along with the check name, category, description, severity, and status (fail or pass). You can also click on each check to view its description and example of the possible issue in detail. This example is context-sensitive and you can use it to fix the issue in your uploaded document. Traceable also lists the potential vulnerabilities detected by that check.

If you fix either of the failed checks in the OpenAPI document, Traceable runs the API inspector and updates its status accordingly.