Optional OpenAPI Endpoints for TAP 1.2 / User-managed Tables

[Gregory MANTELET]

Hi Pat, Joshua

I like this solution of describing the endpoint anyway, but declare that 
it may not be implemented through a human text in the IVOA spec, but 
also with the additional HTTP status code in the OpenAPI description.

Then, about the status code, I have to say that I tend to prefer /HTTP 
501 - Not implemented/.

Firstly, because the feature is /really/ not implemented whereas 405 
textually means that the client is not allowed to perform this action. 
In our case, it is not a question of authorization, but really of "the 
server is not capable to do that".

Secondly, 4xx errors are errors due to something wrong in the request 
sent by a client, whereas 5xx are errors due to a problem on 
server-side. In our case, the client would not do anything wrong. So, a 
5xx error seems more natural.

Finally, if we refer to RFC 9110 
<https://www.rfc-editor.org/rfc/rfc9110> we have the following texts:

    ----
>     15.5.6. 405 Method Not Allowed
>     <https://www.rfc-editor.org/rfc/rfc9110#name-405-method-not-allowed>
>
>     The 405 (Method Not Allowed) status code indicates that the method
>     received in the *request-line is known by the origin server but
>     not supported by the target resource.* The origin server MUST
>     generate an Allow header field in a 405 response containing a list
>     of the target resource's currently supported methods.

>     15.6.2. 501 Not Implemented
>     <https://www.rfc-editor.org/rfc/rfc9110#status.501>
>
>     The 501 (Not Implemented) status code indicates that the server
>     does not support the functionality required to fulfill the
>     request. This is the appropriate response when *the server does
>     not recognize the request method and is not capable of supporting
>     it for any resource*.

>     9.1. Overview <https://www.rfc-editor.org/rfc/rfc9110#name-overview>
>     [...]
>     *An origin server that receives a request method that is
>     unrecognized _or_ not implementedSHOULDrespond with the501 (Not
>     Implemented)
>     <https://www.rfc-editor.org/rfc/rfc9110#status.501>***status code.
>     An origin server that receives a request method that is recognized
>     and implemented, but not allowed for the target
>     resource,SHOULDrespond with the405 (Method Not Allowed)
>     <https://www.rfc-editor.org/rfc/rfc9110#status.405>status code.
    ----


Both status codes do seem OK for me, but for all these reasons 501 seems 
to be the best match.
Of course, this is my personal opinion here, so I now leave the final 
decision to both of you.

Cheers,
Grégory M.


On 27/11/2024 04:14, Patrick Dowler via dal wrote:
> 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/20241129/7427678d/attachment.htm>