Optional OpenAPI Endpoints for TAP 1.2 / User-managed Tables

[Patrick Dowler]

I was also thinking along those lines, but considered 405 "Method Not
Allowed" which also seems to fit. I'd have to test, but I think web
frameworks respond with a 405 if you do not configure/implement a specific
method (eg PUT) so correct implementation could be achieved with zero
effort. I expect 501 would require something be done.

I will keep both in mind for when I get back to this.

--
Patrick Dowler
Canadian Astronomy Data Centre
Victoria, BC, Canada


On Tue, 26 Nov 2024 at 08:10, Joshua Fraustro <jfraustro at stsci.edu> wrote:

> 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/fe3a414a/attachment.htm>