OpenAPI Schemas

https://bugs.launchpad.net/keystone/+spec/openapi

We would like to start documenting our APIs in an industry-standard, machine-readable manner. Doing so opens up many opportunities for both OpenStack developer and OpenStack users alike, notably the ability to both auto-generate and auto-validate both client tooling and documentation alike. Of the many API description languages available, OpenAPI (fka “Swagger”) appears to be the one with both the largest developer mindshare and the one that would be the best fit for OpenStack due to the existing tooling used in many OpenStack services, thus we would opt to use this format.

Problem Description

The history of API description languages has been mainly a history of half-baked ideas, unnecessary complication, and in general lots of failure. This history has been reflected in OpenStack’s own history of attempting to document APIs, starting with our early use of WADL through to our experiments with Swagger 2.0 and RAML, leading to today’s use of our custom os_api_ref project, built on reStructuredText and Sphinx.

It is only in recent years that things have started to stabilise somewhat, with the development of widely used API description languages like OpenAPI, RAML and API Blueprint, as well as supporting SaaS tools such as Postman and Apigee. OpenAPI in particular has seen broad adoption across multiple sectors, with sites as varied as CloudFlare and GitHub providing OpenAPI schemas for their APIs. OpenAPI has evolved significantly in recent years and now supports a wide variety of API patterns including things like webhooks. Even more beneficial for OpenStack, OpenAPI 3.1 is a full superset of JSON Schema meaning we have the ability to re-use much of the validation we already have.

Use Cases

As an end user, I would like to have access to machine-readable, fully validated documentation for the APIs I will be interacting with.

As an end user, I want statically viewable documentation hosted as part of the existing docs site without requiring a running instance of Keystone.

As an SDK/client developer, I would like to be able to auto-generate bindings and clients, promoting consistency and minimising the amount of manual work needed to develop and maintain these.

As a Keystone developer, I would like to have a verified API specification that I can use should I need to replace the libraries we use in the event they are no longer maintained.

Proposed Change

This effort can be broken into a number of distinct steps:

  • Add missing request body and query string schemas

    These schemas will merely validate what is already allowed, which means extensive use of "additionalProperties": true or empty schemas.

    Once these are added, tests will be added to ensure all API resource have appropriate schemas.

  • Add response body schemas

    These will be sourced from both existing OpenAPI schemas, currently published at https://opendev.org/openstack/codegenerator, and from new schemas auto-generated from JSON response bodies generated in tests and manually modified handle things like enum values.

    Once these are added, tests will be added to ensure all API resource have appropriate response body schemas. In addition, we will add a new configuration option that will control how we do verification at the API layer, [api] response_validation. This will be an enum value with three options:

    error

    Raise a HTTP 500 (Server Error) in the event that an API returns an “invalid” response.

    This will be the default in CI i.e. for our unit, functional and integration tests. Eventually this could be the default for production also.

    warn

    Log a warning about an “invalid” response, prompting operations to file a bug report against Nova.

    This will be initial (and likely forever) default in production.

    ignore

    Disable API response body validation entirely. This is an escape hatch in case we mess up.

Note

The development of tooling required to gather these JSON Schema schemas and generate an OpenAPI schema will not be developed inside Keystone and is therefore not covered by this spec. Keystone will merely consume the resulting tooling for use in documentation.

Alternatives

  • Use a different tool

    OpenAPI has been chosen because it is the most widely used API description language available and matches well with our existing use of JSON Schema for API validation.

  • Maintain these specs out-of-tree

    This prevents us testing these on each commit to Keystone and means work that could be spread across multiple teams is instead focused on one small team.

Security Impact

None

Notifications Impact

None

Other End User Impact

This should be very beneficial for users who are interested in developing client and bindings for OpenStack. In particular, this should (after an initial effort in code generation) reduce the workload of the SDK team as well as teams outside of OpenStack that work on client tooling such as the Gophercloud team.

Performance Impact

There will be a minimal impact on API performance as we will now verify both requests and responses for all API resources. Given our existing extensive use of JSON Schema for API validation, it is expected that this should not be a significant issue.

Other Deployer Impact

None

Developer Impact

Developers working on the API microversions will now be encouraged to provide JSON Schema schemas for both requests and responses.

Implementation

Assignee(s)

Primary assignee:

gtema

Work Items

  • Add missing request body schemas

  • Add tests to validate existence of request body schemas

  • Add missing query string schemas

  • Add tests to validate existence of query string schemas

  • Add response body schemas

  • Add decorator to validate response body schemas against response

  • Add tests to validate existence of response body schemas

  • Add description to the API methods and bodies that are used in the OpenAPI spec

Dependencies

The actual generation of an OpenAPI documentation will be achieved via a separate tool. It is not yet determined if this tool will live inside an existing project, such as os_api_ref or openstacksdk, or inside a wholly new project. In any case, it is envisaged that this tool will handle OpenStack-specific nuances like microversions that don’t map 1:1 to OpenAPI concepts in a consistent and documented fashion.

Documentation Impact

Initially there should be no impact as we will continue to use os_api_ref as-is for our api-ref docs. Eventually we will replace or extend this extension to generate documentation from our OpenAPI schema.

References