Use OpenAPI to define MDS API request shapes and query parameters #281
Description
The existing documentation of query parameters and headers is in narrative format in the Provider and Agency README files. This is useful to give an overview of what's allowed, but because it is not programmatically enforced and left up to interpretation, it's common to see divergences from the spec. [1]
I'd like to propose adding API endpoint parameter definitions to Provider (and maybe Agency?) endpoints using a format designed to support automatic validation.
Implementers of MDS endpoints and software that interacts with them would be able to use these definitions to validate the shape of query parameters and headers for incoming requests. Additionally, a rigorous definition of the request shape would let MDS evolve to support more advanced request formats in a safe and transparent way.
A framework frequently used for this kind of schema is OpenAPI v3, an evolution of Swagger API definition formats. It has a lot of OSS and third party tools for API documentation and validation that may come in useful, and is reasonably well documented. Based on prior experience, I'd recommend using this format. [2]
[1] A similar thing to this already exists for validating the shape of responses via JSON Schema, and has been extremely useful for deciding if an API response conforms to the specification. However, JSON Schema is a toolkit for asserting the shape of JSON objects and does not really support defining the shape of request parameters and headers.
[2] I also considered suggesting JSON Hyper Schema (narrative intro), an extension to JSON Schema that builds a vocabulary for defining URI shapes. However, it is very young and does not have a really mature ecosystem of tools around it yet.