HTTP Options Response Body

[nateklaiber]

The Standards for Request & Response state that:

HTTP OPTIONS method MUST NOT contain a request or response body

RFC 2626 states that:

The OPTIONS method represents a request for information about the communication options available on the request/response chain identified by the Request-URI. This method allows the client to determine the options and/or requirements associated with a resource, or the capabilities of a service, without implying a resource action or initiating a resource retrieval.

It later goes on to say:

A 200 response SHOULD include any header fields that indicate
optional features implemented by the server and applicable to that
resource (e.g., Allow), possibly including extensions not defined by
this specification. The response body, if any, SHOULD also include
information about the communication options. The format for such a
body is not defined by this specification, but might be defined by
future extensions to HTTP. Content negotiation MAY be used to select
the appropriate response format. If no response body is included, the
response MUST include a Content-Length field with a field-value of
"0".

With this, I often use OPTIONS in conjunction with OpenAPI. I can make a request with an Accept: application/vnd.oai.openapi+json header specified. The response returns the standard OPTIONS headers to inform Allow, Cache Control, and other aspects.

The response body is the OpenAPI specification for that specific Request Model (Serializations), Request information, and Response Model (Serializations).

This way my SDKs can programmatically retrieve information about that specific resource.

Then, these are all collated up to the root directory which provides a fully qualified OpenAPI specification for the entire platform and is browse-able in Swagger (or other UI).

I'm curious why the standard would say MUST NOT contain a response body?

[ca0abinary]

@nateklaiber In this case I would focus on this part of the spec

The response body, if any, SHOULD also include information about the communication options.

The example you provided uses OPTIONS to provide data not specifically related to "communication options" (e.g.: accepted verbs, CORS, expirations, and the like) but rather as an SDK documentation resource.

It's a clever idea, but I would encourage a well-known endpoint as opposed to a solution like this. For example the swagger integration with .net via Swashbuckle provides a /swagger endpoint and the ruby gem rswag provides /api-docs as a browsable resource useful both programmatically and for end users.

[nateklaiber]

@ca0abinary - That's not exactly true. The endpoint responds with the OpenAPI specification, which is directly related to communication options - HTTP Methods (Verbs), parameters, schema, security (OAuth), etc.

From a REST standpoint, the OpenAPI mime type is simply another representation of the resource in question. The OPTIONS method makes sense, as the purpose is to communication your communication options with the platform. In fact, the Allow header returns the available methods, and each of those are represented in the OpenAPI response body.

My only mention of SDK is that in my SDKs I also have a utility that can read OpenAPI JSON serialization, permitting me to use it like I would any other domain model that consumes JSON serializations (GeoJSON, JSON Data Table, etc).

I have made an intentional decision to not use other tools that hijack other mechanisms or areas of concerns (which I believe rswag does). I would argue this is where rswag tries to be clever, but in doing so conflates the concerns of 'specs' and 'OpenAPI'. I don't need a custom DSL to test my modeling and serializations - those are standard unit tests and integration tests. In fact, those should be tested independent of OpenAPI. My litmus test for this is: do I have custom DSLs for any other area of concern/context in my code? Why would I have a custom DSL for OpenAPI, but not for GeoJSON, or other more specific schemas? Why should OpenAPI be any different?

And, as in testing, I also need to make sure that rswag is fully tested as well. I'm adding more complexity and dependencies to the test suite.

There have been other attempts to also hijack code documentation (YARD) and inject it with OpenAPI specifications. Again, this is the wrong place and it conflates two different concerns.

The root of my API platforms are always a 'directory' or 'phone book' of all possible routes available. This is rendered as a collection of links that are fully qualified or URI templates that can be expanded. The root also has a /documentation/releases/* that provides you with a full view of routes, link relationships (IANA or custom), errors, etc. There is also a base OpenAPI specification. When I ask for the root URL with OPTIONS as OpenAPI, I get the fully qualified specification (it gets cached at deploy time) that includes all available versions/hosts/etc.

I get it at the base of a version or I can simply ask for it for a specific resource. It is introspection on the resource and all communication options available.

This can then be downloaded, or, as I do, I use that reference inside of Swagger UI to then render the interface to browse and test out the API.

[travisgosselin]

Agreed that is a neat and a pretty clever way to handle it. While I appreciate the usage of OpenAPI as a description of the endpoint, it feels odd to return the entire open API spec for the OPTIONS usage of a specific resource. Similarly, it might feel weird getting an OpenAPI spec that only provides just that endpoint/verb set (not sure if you called out which method you are taking above).

That being said, while we have coupled our design process at SPS Commerce to OpenAPI as our ubiquitous design language, I'm not convinced that I should be making that assumption to consumers of the API (personally it is not a problem as I use it everywhere as well). I do love the closer we can get to "self-describing" APIs, but I'm not convinced that OpenAPI is better for that on the consumer side over Hypermedia and potentially even with JSON-LD. These SPS API standards are currently only at a Richardson Maturity Model Level 2 without more self-description and taking the next steps towards hypermedia. Until these API Standards take a direction or stance on moving to maturity level 3, I think it is important that OPTIONS remains without a body, making that transition later slightly easier if necessary, and aligning on the CORE needs of the REST-ful style resource implementation. The focus here is on RESTful style resources ... there may be plenty of good reasons to include a body on OPTIONS outside of that style.

[nateklaiber]

Thanks for the response @travisgosselin

To your first point, I use content negotiation to determine it. I do this in the same way as I do with table-based structures (CSV or JSON Data Table). For example, I may want to grab a CSV file that has 200 rows, but the default pagination is 25 records per page (disregard asynchronous as an approach here, as both can be used and are viable). I will make my requests for the max set I can (lets say 100 records), then I will follow pagination links (hypermedia) and stitch my records together. In these cases, I don't need the fully qualified HEADER with every request (though I could, and simply discard it on subsequent requests). There are concerns here that can be addressed by schemas where I can get it all, or can get body and discard headers/footers. I use vendor extension mime types, which are also defined and available in my OpenAPI specification.

The same is true for OpenAPI. I can choose to have a fully qualified OpenAPI response for that resource. Still useful as it will have all information.

Or I could choose to only get the resource level definition (which is what my Request model serialization defines).

This is also how the deploy precompile tasks works. The root level has the main OpenAPI definition, and then for each route in the 'phone book' - it will retrieve the OpenAPI serialization for each resource and inject them (think of this like the precompile for Assets where it concats files). The output is a fully cached API specification bound to that release. Driven by the code itself. Not designed and stored in a separate repository. Available via HTTP (not a separate Github repository where I have to get your separate defined OpenAPI). It's served through the asset host with caching (md5 fingerprint) applied. It's also provided as a symlink to latest (but you could also get previous versions).

I believe you can have both, and you can do so by adhering to well structured HTTP.

To your second point, none of this actually binds itself to OpenAPI at all. It just so happens this is what we use as well (on top of interfaces like Swagger). I could just as easily ask for the OPTIONS request and pass in an Accept header of any other schema/mime type and get that back. I could ask for it with JSON-LD if we supported the serialization. It all depends on what your API wants to support. The possibilities are endless, and they're up to you.

It's REST - a resource and a representation. We just so happen to use OpenAPI. The same way I can ask for a Sales Invoice as JSON, JSON Data Table, PDF, CSV, or Excel. I can ask for OpenAPI, JSON-LD, or any other inflection/documentation framework. If it's not supported, we return a 406 Not Acceptable.

Also, in regards to hypermedia, I use embedded linking in resources where available (JSON, for instance). And, where not available I use the HTTP link header. So all of these still adhere to the available hypermedia. And, the Links are all the same underlying object. I simply serialize links as JSON, JSON Table (think: rake routes), or a Link Header as defined in the specification. A Link resource gets represented as whatever is needed.

My apologies for a dive into a separate topic of Hypermedia in this thread. We can save that for another discussion 🤓

[travisgosselin]

haha no worries. That all sounds really interesting - I always appreciate hearing about how different people have structured their APIs. Definitely have not experienced an API with some of the capabilities you describe - but it sounds like you have a pretty mature pattern that is working really well. Will ponder on this more as we continue to advance our API standards and implementations.