Tanzu Service Mesh automatically scans an API specification to validate it for problems and generates API scores based on the scans. The scores indicate the quality and coverage of the API documentation, compliance with the OpenAPI standards, health, and security of the API specification. You can view the API scores and recommendations for any problems found.

Based on the feedback and recommendations, you can edit your API specification, improve the design and security posture of your API, and thus improve the API scores.

After scanning an API specification, Tanzu Service Mesh generates the following scores:

  • Documentation Health score

  • OpenAPI Health score

  • Security score

  • Governance score

The Documentation Health validation evaluates and validates the API specification for documentation quality and coverage and generates a Documentation Health score. The API documentation is evaluated against three areas:

  • Documentation of operations. The validation checks whether the paths and operations in the API specification are properly described.

  • Documentation of domains. The validation checks whether the domains (tags) are properly described.

  • Documentation of data structures. The validation checks whether the objects in the components object in the specification are properly described.

Tanzu Service Mesh evaluates these documentation areas and and generates a health score for each. The individual area scores are then considered to generate an aggregate Documentation Health score.

The OpenAPI Health validation evaluates the API specification for compliance with OpenAPI standards by using a built-in set of linting and schema validation rules. For example, the OpenAPI Health validation checks the specification for things like use of valid HTTP verbs and use of lower snake case (lower_snake_case) in query parameter names. To calculate an OpenAPI Heatlh score, Tanzu Service Mesh considers the following:

  • Total number of rules

  • Number of occurrences of each violated rule

  • Number of entities (for example, API paths or operations) where a violation occurred

  • Health scores of individual rules

The Security validation scans the API specification for security problems by using a built-in set of static security rules. For example, the Security validation checks the specification for things like use of only secure connections in the servers object and presence of an API key in the security scheme. To calculate a Security score, Tanzu Service Mesh considers the following:

  • Total number of rules

  • Number of occurrences of each violated rule

  • Number of entities (for example, API paths or operations) where a violation occurred

  • Health scores of individual rules

The Governance score helps you understand if the API has any breaking changes. The Governance validation checks the API specification for breaking changes by comparing the latest version of the specification in the primary branch in the GitHub repository against an earlier version that was created internally in Tanzu Service Mesh. If any breaking changes are detected (for example, an endpoint was deleted) as a result of the comparison, Tanzu Service Mesh displays a warning at the top of the API details page. You can click the link in the warning to view what caused the breaking changes.

To calculate a Governance score, Tanzu Service Mesh considers the following:

  • Total number of changes in the API specification

  • Number of breaking changes

  • What factors are considered in calculation

  • Number of nonbreaking changes

  • The weight of breaking and nonbreaking changes

Note:

Currently, breaking and nonbreaking changes have the same weight.

Perform the following procedure to view the API scores and details about the problems with the specification, including breaking changes.

Prerequisites

  • Access the Tanzu Service Mesh Console.

  • API validation and scoring is available only for configured APIs. Verify that you are familiar with the concept of a configured API. For information about configured APIs, see Configured APIs.

  • Verify that you are familiar with OpenAPI Specification concepts such as paths, operations, and tags.

Procedure

  1. In the navigation pane on the left, click API Management.
  2. In the table on the API Management page, click the name of the configured API whose scores you want to view.
  3. On the API details page, click the Validation tab.

    The Validation tab displays the Documentation Quality, OpenAPI Health, Security, and Governance scores generated for the API specification. The scores are expressed as a percentage of total health or compliance in the respective areas. A green score indicates that the specification is in good health in that area. A red score indicates that there are problems in that area require your attention.

    Note:

    • The scores are rounded to the next whole number.

    • A Governance score of 0% is displayed if there is no local version of the specification in Tanzu Service Mesh to compare the latest version in the git repository against.

    If any breaking changes are detected in the API specification, Tanzu Service Mesh displays a red warning Breaking Changes Detected in selected branch Specification at the top of the page (as shown below). To view the errors that caused the breaking changes on the Governance Score subtab, click Show Errors. For more information, see step 7.



  4. To view the details about the Documentation Quality score and about the documentation problems found, click the Documentation Health subtab.

    The left panel displays the health scores for the three documentation areas.

    Note:

    • A health score is not displayed for the Data Structures documentation area if the components object was not found in the API specification.

    • A health score is not displayed for the Domains documentation area if no domains (tags) were found in the API specification.

    The documentation analysis panel for each area on the right provides individual quality and coverage scores. For example, the Operations documentation analysis panel displays a quality score and a coverage score for each domain in the specification.

    To browse through the quality and coverage scores for each area, at the top of the documentation analysis panel, click Next or Previous.

  5. To view the details about the OpenAPI Health score and about the found violations of the OpenAPI standard, click the OpenAPI Health subtab.

    The left panel displays the improvement areas that contain violations and the compliant areas that are fully compliant with the OpenAPI standard.

    A health score and the number of entities where a violation occurs are displayed for each improvement area. To view the details about a violation in the right panel, click the associated improvement area.

  6. To view the details about the Security score and about the security problems found, click the Security Score subtab.

    The left panel displays the improvement areas that contain security problems and the compliant areas that are secure according to the rule set in use.

    A health score and the number of entities where a security problem occurs are displayed for each improvement area. To view the details about a problem in the right panel, click the associated improvement area.

  7. To view the details about the Governance score and about the detected breaking changes, click the Governance Score subtab.

    The left panel displays the different categories of the API specification where breaking changes can occur. For example, if an endpoint was deleted from the specification, that change is indicated as a breaking change under Paths & Endpoints. The Severity column indicates the severity of each breaking change (for example, Critical).

    To view the details of what caused a breaking change in the right panel, click the description of the breaking change in the left panel. See the screenshot in step 3.