API Documentation and Validation Rules

Improving the Quality and Consistency of APIs with OpenAPI Documentation Rules and API Validation / API Linting Rules

The OpenAPI Specification (OAS)

The OpenAPI Specification (OAS) defines a standard, programming language agnostic interface description for REST APIs. Importantly, the specification is widely supported by API Management platforms, development frameworks, testing platforms, code generation tools, and by a number of modelling platforms.

The OAS specifies the rules and syntax required to describe the API’s interface.

Adoption of the most current, generally supported specification version is recommended. Take the time to research the level of support offered by commercial API management platforms — including both gateway and developer portal support for key features.

High Level Documentation Rules

API developers should familiarise themselves with OAS specification guidance and align with enterprise API design guidance. When defining RESTful resource APIs, developers (and OpenAPI templates) should adhere to the following high level documentation rules:

• Resource names must follow REST API Naming Conventions and should be a plural noun such as ‘applications’ or ‘applicants’.
• To aid comprehension and discoverability and to control the impact of changes, a versioned API will ideally model a single core resource, together with any dependent objects and entities. The name of the OpenAPI document should reflect the name of the parent resource — e.g. ‘applications’.
• Align the document with enterprise case conventions — e.g. lowerCamelCase
• Ensure that hierarchical, namespaced API Path Conventions are followed.
• The name of the API resource & document should NOT be namespaced with hyphenated leading name-parts; API paths, teams and groups should provide domain & sub-domain namespacing. e.g. /membership/v1/applications NOT membership-applications
• The OpenAPI “info” object “version” field MUST be present, and MUST contain the full semantic version number of the API — e.g. “version: 2.3.1”. Only major version numbers embedded into URLs.
• The OpenAPI ‘info’ object MUST contain a ‘contact’ object containing a monitored contact email address and/or URL that the client can use to contact the team with issues and comments. E.g.

contact:
  name: myAPI Support
  email: support@myorg.com

• API request and response examples SHOULD be included in the specification document to assist client developers.
• The API specification is a contract — where a field is required for successful processing, it MUST be modelled in the API specification as “required”.
• Reference a components.schemas definition for payload. Resource instance payloads will be substantially similar across POST (request), PUT (request), GET (response) and PATCH (update), and SHOULD reference the same schema where possible. To minimize duplication and redundancy, consider Inheritance and Polymorphism.
• The resource Id is always generated by the System-of-Record and is always immutable. A resource Id field in OpenAPI 3.x MUST be defined as “readOnly”. This ensures that POST, PUT and PATCH operations on a resource do not display a resource Id as an applicable field.

API Validation

Governance of API design standards and security policy compliance must be automated wherever possible. OpenAPI document linting is supported by some IDEs, and CI/CD pipelines incorporating OpenAPI document linting can provide feedback on API quality and enforce mandatory API standards and patterns.

Spectral — Open Source OpenAPI/AsyncAPI Linter

Spectral is a widely used open-source OpenAPI/AsyncAPI document linter, and Spectral OpenAPI rules are widely referenced as a base OpenAPI document ruleset. These rules may be easily modified or extended to provide automated API document quality governance in alignment with API design guidance. The ruleset includes both stylistic warnings and mandatory rules, including:

• info-description: OpenAPI object info description must be present and non-empty string.
• operation-description: Under each operation a description must be present and non-empty string.
• operation-operationId: The operation ID is a reference for the operation, used to suggest a connection to other operations. This parallels HATEOAS referencing. Every operation must have a unique operationId
• operation-success-response: Operation must have at least one 2xx or 3xx response. If you forget to write out a success case for this API, then this rule will let you know.
• path-declarations-must-exist: Path parameter declarations cannot be empty, ex./given/{} is invalid.
• path-not-include-query: Don’t put query string items in the path, they belong in parameters with in: query.
• path-params: Path parameters are correct and valid. For every parameter referenced in the path string (i.e: /users/{userId}), the parameter must be defined in either path.parameters, or operation.parameters objects. Every path.parameters and operation.parameters parameter must be used in the path string.
• typed-enum: Enum values should respect the type specifier.
• oas3-operation-security-defined: Operation security values must match a scheme defined in the components.securitySchemes object.
• oas3-schema: Validate structure of OpenAPI v3 specification.
• oas3-server-trailing-slash: Server URL should not have a trailing slash.
• oas3-valid-schema-example: Examples must be valid against their defined schema. This rule is applied to Schema objects.

Rule Severity

During deployment to sandbox environments, deployment linting should return only warnings. During deployment to connected dev, integrated testing, acceptance and production environments, linting should return an error severity and fail deployment for infringement of mandatory rules. Product team continuous integration linting should align during these delivery phases.

Example mandatory rule (validation error): An “info” object “version” field MUST be present, and MUST contain the full semantic version number of the API , e.g. “version: 2.3.1”. Linting should ensure that the major version number aligns with versioned URLs.

Example recommendation (validation warning): API request and response examples SHOULD be included in the specification document to assist client developers.

Documentation and Maintenance of Validation Rulesets

OpenAPI document linting rules should be clearly defined and documented so that developers understand their responsibilities.

Extension rulesets can be easily configured via the Stoplight free tier (web or locally installed) and must be maintained and made available for integration into IDE tools and CI/CD pipelines by the API platform or competency team.

API Validation Tools and Methods

There are several methods available to lint your API with spectral, including:

• Visual Studio Code : Install the ‘Spectral’ extension by Stoplight. Rule errors and warnings are listed in the Problem console, and is updated dynamically as changes are made.
• Stoplight Studio : Upload an OpenAPI spec, or paste into the code editor, and the spectral base-ruleset will automatically provide feedback. The warning icon will toggle a side-by-side view.
• CI/CD pipeline : As well as automated Sonarqube analysis of your software source code, integration & build pipelines can support spectral linting of your OpenAPI definition to ensure the earliest possible feedback on document quality issues.

Validation will return non-blocking warnings that align with best practice (‘should’) API design guidance, as well as errors corresponding to mandatory (‘must’) design guidance that should fail code integration and build or deployment of an OpenAPI specification.

More here on Model Driven, Integrated DevOps.

Wrap-up

OpenAPI 3.x is the leading specification for the documentation of synchronous HTTP APIs, and it enjoys widespread platform support. API developers will need to be familiar with both OAS specification guidance and enterprise API design guidance in order to produce consistent, quality API documentation. API validation (e.g. Spectral) should be employed to improve the quality and consistency of API documentation and enforce mandatory rules.