Optional OpenAPI Endpoints for TAP 1.2 / User-managed Tables

[Joshua Fraustro]

Hi Pat, DAL,

At the Malta Interop, you mentioned in your presentation on user-managed tables that you were looking for a method to denote that the extended API operations were optional in the OpenAPI definition.

As you pointed out, I don’t think there’s a built-in way to do so in the OpenAPI specification. This is likely because the concept of defining the “possible existence” of a path operation isn’t quite in line with the intent of OpenAPI to begin with—to borrow Markus’s line: “Optionality Considered Harmful.”

That said, to mark the optional nature of the new endpoint operations, I suggest the following:

  1.  Include an HTTP 501 – Not Implemented response as one of the acceptable responses for the endpoint.
  2.  Use verbiage in both the OpenAPI description of the operation and in the standards document to clarify that the operation is optionally supported by the server.

For example:

/tables:
  get: …
  put:
    summary: Upload a persistent table
    description: >
      This endpoint is optional and may not be implemented on all servers.
      If not implemented, it should return a `501 Not Implemented`.
    responses:
      '200': …
      '501':
        description: This feature is not implemented.

Additionally, the standards document could include a statement like: “Services that do not implement this operation must respond with an HTTP status code 501 Not Implemented when requests are made to the endpoint.”

I think there are a few advantages to this approach, chiefly that it stays within established HTTP/OpenAPI practices. Additionally, validators will have a straightforward way to test and verify the implementation.

I hesitate to even mention it, but another possibility would be defining an IVOA vendor-specific extension (e.g., x-optional-endpoint: true). However, I’d strongly discourage us from even considering this—part of my push for OpenAPI adoption is that we (IVOA) stop inventing bespoke ways of doing every little thing...

Thanks,
Joshua Fraustro

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.ivoa.net/pipermail/dal/attachments/20241126/6464069a/attachment.htm>