How should we mark endpoints as required in the OpenAPI Spec?

Technical
1

I’m seeking input from people if you have an opinion on the technical method we use to mark HSDS API endpoints as REQUIREd in the OpenAPI.json file. This is to a) support future validation tooling producing a compliance report and b) bringing the OpenAPI file in line with the current specification.

Currently, the only REQUIRED endpoints in the specification are:

  • /
  • /services
  • /services/{id}

The contradiction I’m trying to resolve is that OpenAPI is really designed for describing a single instance of an API, rather than prescribing how an API should conform to a specification. Therefore it lacks features such as marking endpoints as required.

This has the effect that anyone trying to implement API validation needs to maintain a separate list of the endpoints required by the HSDS Specification, in order to decide whether the overall API is conformant or not i.e. “your endpoints are all producing valid data, but you lack the /services/{id} endpoint so sadly you’re not compliant with the specification”

I noticed that the CommonGrants folk got around this by using OpenAPI’s Tag object, and tagged particular endpoints with required.

An alternative way to do this is to extend OpenAPI’s specification with a custom field which would mark the endpoint as required. This is supported by OpenAPI’s specification:

Both approaches are similar in terms of pragmatics. We’d either create a required tag in our OpenAPI specification docs and apply it to endpoints, or we’d create a x-required: true property and apply it to endpoints.

See also the Github issue I raised on this:

2

I ran this by our old friend Kin Lane, API Evangelist and OpenAPI expert. He says:

“Your three options are 1) Tags, 2) Extensions, 3) Separate OpenAPIs for required or additional paths / operations and being explicit in the description.”