Skip to content
API Cloud

Qualitative Metrics for API Specification

The Qualitative Metrics tab provides deeper API design and documentation quality insights based on the uploaded OpenAPI specification. These insights help publishers improve clarity, consistency, and consumer experience.

To review qualitative metrics:

  1. From the Trimble Cloud Console left menu, select APIs.
  2. Select the API version and open the API Specification tab.
  3. Upload or update the OpenAPI specification.
  4. Select the Qualitative Metrics tab.
  5. Review the quality ratings shown for the specification.
  6. Update and re-upload the specification to verify improved qualitative results.

Use qualitative metrics alongside linting metrics to continuously improve API documentation quality before broad publication.

Qualitative Metrics Tab

How qualitative metrics are calculated:

API Cloud uses an AI-based review process to evaluate your uploaded OpenAPI specification and generate quality scores. The evaluation is based on high-level documentation criteria, including:

  • Verb Alignment: Checks whether methods like GET, POST, PUT, and DELETE are used in a way that matches the endpoint purpose.
  • Clarity and Consistency: Checks whether descriptions are clear and consistent across endpoints.
  • Tone and Understandability: Checks whether wording is simple, neutral, and easy for developers to follow.
  • Internationalization and Localization: Checks whether documentation considers global users, languages, and locale-related behavior.
  • Readability Score: Checks whether content is easy to read and not overly complex.
  • Path Accuracy: Checks whether endpoint paths are correctly documented, including path parameters such as {id}.
  • Parameter Alignment: Checks whether query, path, header, and body parameters are correctly described and match the spec.
  • Error Messages and Troubleshooting: Checks whether error responses are meaningful and include guidance to resolve issues.
  • Examples and Use Cases: Checks whether request and response examples help users understand real usage.
  • Versioning and Deprecation: Checks whether API versions and deprecated behavior are clearly communicated.

Each area is scored to highlight strengths and gaps. Missing or unclear information receives lower scores. These ratings are guidance-oriented and may vary slightly between evaluations of the same specification.