Scribd
Upload
69 views7 pages

API Documentation and Validation Rules - by TRGoodwill - API Central - Medium

The document discusses improving API quality and consistency through OpenAPI documentation rules and API validation. It recommends adopting the OpenAPI Specification to describe REST APIs in a standard way. It provides high-level documentation rules for resource naming, versioning, examples, and more. It also describes using the open-source Spectral tool to lint OpenAPI documents and enforce rules through warnings and errors. Maintaining validation rulesets is important for developers to understand documentation responsibilities.

Uploaded by

teo
Copyright
© © All Rights Reserved
We take content rights seriously. If you suspect this is your content, claim it here.
Available Formats
Download as PDF, TXT or read online on Scribd
69 views7 pages

API Documentation and Validation Rules - by TRGoodwill - API Central - Medium

The document discusses improving API quality and consistency through OpenAPI documentation rules and API validation. It recommends adopting the OpenAPI Specification to describe REST APIs in a standard way. It provides high-level documentation rules for resource naming, versioning, examples, and more. It also describes using the open-source Spectral tool to lint OpenAPI documents and enforce rules through warnings and errors. Maintaining validation rulesets is important for developers to understand documentation responsibilities.

Uploaded by

teo
Copyright
© © All Rights Reserved
We take content rights seriously. If you suspect this is your content, claim it here.
Available Formats
Download as PDF, TXT or read online on Scribd
You are on page 1/ 7

API Documentation and Validation

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

TRGoodwill · Follow
Published in API Central · 5 min read · May 5

26

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: [email protected]
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.

Open in app
Stoplight Studio : Upload an OpenAPI spec, or paste into the code editor,
Search Write
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.

Api Development Openapi Api Documentation Api Linting Api Validation

You might also like