Validating API specifications in API Insights

  • Release version: Yokohama
  • Updated June 23, 2025
  • 3 minutes to read
    • Summarize
    Summarized using AI
    This content was generated using new OpenAI-powered functionality. Results are provided on an as is basis and are not guaranteed to be accurate or complete.

    Summary of Validating API specifications in API Insights

    API Insights provides validation rules to verify that your API specifications are complete, consistent, and aligned with best practices. These rules help identify structural issues early during import or analysis, enhancing API quality and standardization. By managing validation rules, you can reduce errors by detecting missing or incorrect fields before APIs are published or used in production.

    Show full answer Show less

    API Specification Storage

    API specifications are stored in the API Specification [snapiinsightswsapispecification] table, which holds the full content of API documents and key metadata, including:

    • Name: API name
    • Version: API version
    • Type: Specification format and version (e.g., OpenAPI 3.0.0)
    • State: Validation status—Unprocessed, Valid (with possible warnings), or Invalid (with errors)
    • Specification: Full specification content including endpoints and schema
    • Message: Validation messages showing errors or warnings

    Validation Rule Structure

    Validation rules are stored in the Specification Validation Rule [snapiinsightswsspecvalidationrule] table and define criteria for checking API specifications. Key components include:

    • Specification: Target API specification type
    • Version: Specific versions the rule applies to (optional)
    • Type: Validation type such as path presence or expected values
    • Key: Specific fields to verify
    • Value: Expected values for keys (if applicable)
    • Severity: Warning or error level of the validation
    • Message: Explanation shown when the rule triggers
    • Active: Whether the rule is enabled for validation

    Role requirements: Editing or deleting rules requires the sncmdbeditor role; viewing requires cmdbread.

    Validation Process

    The API Specification Validation scheduled job automatically validates unprocessed API specifications against active rules based on the specification type. The process:

    • Fetches active validation rules
    • Identifies unprocessed API specifications
    • Applies relevant rules to verify required fields and values
    • Updates the specification status as Valid, Invalid, or Valid with warnings
    • Captures and displays error or warning messages for review

    Predefined Rules for OpenAPI Specifications

    API Insights includes default validation rules for OpenAPI specifications to verify critical sections:

    • Validate tags: Ensures each tag has a name field; missing names generate warnings but do not invalidate the spec.
    • Validate required sections: Checks for mandatory top-level sections info, paths, and components; missing sections generate errors and mark the spec invalid.
    • Validate servers section: Verifies presence of the servers section defining server endpoints; absence results in errors and invalid status.

    These rules help maintain the integrity of OpenAPI specifications by confirming essential metadata, endpoint definitions, and tagging consistency.

    You can access API specification validation rules to verify that your API specifications are complete, consistent, and adhere to best practices.

    Validation rules identify structural issues early during import or analysis, improving overall API quality. You can manage these rules to enforce standardization across API specifications and reduce errors by checking for missing or incorrect fields before APIs are published or used in production.

    Storing API specifications

    The API Specification [sn_api_insights_ws_api_specification] table stores the specification documents that describe individual APIs. Each record includes the following details to identify the API to which the specification belongs and to manage multiple versions.
    Table 1. API specification details
    Field Description
    Name Name of the API.
    Version Version of the API.
    Type Format and version of the API specification standard being used. For example, openapi3.0.0 for an OpenAPI specification.
    State Current status indicating whether the API specification has been validated against the applicable rules and the validation outcome. Valid values are:
    • Unprocessed: Indicates that the API specification hasn’t been validated.
    • Valid: Indicates that the API specification was validated and processed successfully or with warnings. If warnings are present, details are displayed in the Message field.
    • Invalid: Indicates that the API specification was validated but contains errors. Error details are displayed in the Message field.
    Specification Full content of the API specification file.
    Note:
    For OpenAPI, includes the complete OpenAPI document describing endpoints, methods, and schema.
    Message Messages are generated after processing all validation rules for the specification type. They include errors or warnings with explanations.

    Validation rule structure

    The Specification Validation Rule [sn_api_insights_ws_spec_validation_rule] table stores validation rules for the API specifications defined in the API Specification [sn_api_insights_ws_api_specification] table.
    Note:
    The sn_cmdb_editor role is required to edit or delete validation rules, and the cmdb_read role to view them.

    Each validation rule contains the following key components:

    Table 2. Validation rule components
    Component Description
    Specification API specification for which the rule is designed.
    Version Version of the API specification the rule validates. If specified, the rule applies only to those versions. To restrict validation to specific versions, specify them in the Version field. Separate multiple values with commas. For example, 1.0,1.1,2.0.
    Note:
    If the Version field is left empty, the rule runs for all installed versions of the specified API specification type.
    Type Type of validation to perform. The valid values are:
    • Path: Verifies that the specific keys are present within arrays of objects, individual objects, or both, in the designated sections of the API specification document.
    • Expected value: Validates whether the specified key matches the expected values specified in the Value field. This validation applies only to a single key specified in the Key field.
    Key Part of the specification to verify. If no expected value is provided, you can enter multiple keys in the Key field, separated by commas.
    Value Expected values for the key specified in the Key field. Separate multiple values with commas.
    Severity Severity level of the validation rule outcome, either a warning or an error.
    Note:
    When set to warning, the API specification remains valid if the rule isn’t met, indicating it is not a failure, and only a message is displayed.
    Message Explanation of the issue when the rule is triggered.
    Active Option to activate the rule. Only active rules are triggered by the API Specification Validation scheduled job.

    API specification validation process

    The API Specification Validation scheduled job automatically validates unprocessed API specifications against active rules based on their specification type to ensure compliance with required standards.

    The validation process includes:
    1. Retrieving all active validation rules from the Specification Validation Rule [sn_api_insights_ws_spec_validation_rule] table.
    2. Selecting APIs marked as unprocessed in the API Specification [sn_api_insights_ws_api_specification] table.
    3. Applying relevant validation rules to each selected API based on its specification type, such as OpenAPI.
    4. Verifying the presence or correctness of specific fields or their values within the API specification.
    5. Updating the processing status and capturing any errors or warnings.

    Predefined rules for OpenAPI specifications

    By default, the application includes the following validation rules for OpenAPI specifications:
    Validate tags
    Verifies that each tag in the API specification includes a name field. If the name field is missing, the system returns a warning message but marks the specification as valid.
    Validate required sections
    Verifies that the API specification includes the required top-level sections: info, paths, and components. If any of these sections are missing, the system returns an error message and marks the specification as invalid.
    Validate servers section
    Verifies whether the API specification includes a servers section that defines the server endpoints. If the servers section is missing, the system returns an error message and marks the specification as invalid.

    These predefined rules verify critical sections such as tagging, metadata, and server definitions in OpenAPI specifications.