Optional OpenAPI Endpoints for TAP 1.2 / User-managed Tables

[Joshua Fraustro]

This is a little sticky and I can definitely see how these could be read either way.

For what it's worth, my go-to resource for these things, https://http.dev/501, also acknowledges the similarity between the two and includes this blurb:

A 405 Method Not Allowed status code suggests that the HTTP request cannot be filled and that the functionality will not be available in the foreseeable future, whereas a 501 Not Implemented status code is used to suggest that it’s “not yet implemented but will be", or “this is something that you can do, once I am ready for you to do it". In this situation, the server can optionally supply a Retry-After HTTP header, suggesting a time for the client to try again.

Reading back-and-forth between the two codes, and your replies, I'm actually starting to prefer 405, if a service isn't going to develop it at all.

Out of curiosity, to confirm what Pat was saying with it being the default response, I did try a simple POST against our service, and 405 is the default response (for our stack, anyway), which is an advantage.
>>> requests.post("https://mast.stsci.edu/vo-tap/api/v0.1/hsc", json={})
<Response [405]>

I appreciate people taking a look, and am glad there is some consensus on the idea at least. As long as we're consistent with it in the OpenAPI doc going forward, I suppose it doesn't matter much.

________________________________
From: Mark Taylor <m.b.taylor at bristol.ac.uk>
Sent: Friday, November 29, 2024 10:04:41 AM
To: Gregory MANTELET
Cc: Patrick Dowler; Joshua Fraustro; dal at ivoa.net
Subject: Re: Optional OpenAPI Endpoints for TAP 1.2 / User-managed Tables

External Email - Use Caution

On Fri, 29 Nov 2024, Gregory MANTELET via dal wrote:

> Finally, if we refer to RFC 9110 <https://urldefense.com/v3/__https://www.rfc-editor.org/rfc/rfc9110__;!!CrWY41Z8OgsX0i-WU-0LuAcUu2o!0ApzGxXgA2HAdc3IVhcvThbKNytXvCPdpdQRoFsyk04P5CeqMWhaFREq8YtZgs4Y30wITC-0yghkSIR_ryLGKBuhito$ > we
> have the following texts:

To me, these support use of 405 not 501 in this case.
Joshua's example was use of PUT to /tables.

> >     15.5.6. 405 Method Not Allowed
> >     <https://urldefense.com/v3/__https://www.rfc-editor.org/rfc/rfc9110*name-405-method-not-allowed__;Iw!!CrWY41Z8OgsX0i-WU-0LuAcUu2o!0ApzGxXgA2HAdc3IVhcvThbKNytXvCPdpdQRoFsyk04P5CeqMWhaFREq8YtZgs4Y30wITC-0yghkSIR_ryLGKBu_DXI$ >
> >
> >     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.

In this case PUT is an HTTP method known to the server,
but not supported by the target resource (/tables), so 405 looks correct.

> >     15.6.2. 501 Not Implemented
> >     <https://urldefense.com/v3/__https://www.rfc-editor.org/rfc/rfc9110*status.501__;Iw!!CrWY41Z8OgsX0i-WU-0LuAcUu2o!0ApzGxXgA2HAdc3IVhcvThbKNytXvCPdpdQRoFsyk04P5CeqMWhaFREq8YtZgs4Y30wITC-0yghkSIR_ryLG4KQ8B24$ >
> >
> >     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*.

The server does recognise the HTTP PUT method and may well support it
for other resources, just not /tables, so 501 is not suitable.

My understanding is that 501 is for an HTTP method that's not
recognised like "FOO" or "DELEET", or perhaps one that's just
not implemented at all by the server.

Mark

--
Mark Taylor  Astronomical Programmer  Physics, Bristol University, UK
m.b.taylor at bristol.ac.uk          https://urldefense.com/v3/__https://www.star.bristol.ac.uk/mbt/__;!!CrWY41Z8OgsX0i-WU-0LuAcUu2o!0ApzGxXgA2HAdc3IVhcvThbKNytXvCPdpdQRoFsyk04P5CeqMWhaFREq8YtZgs4Y30wITC-0yghkSIR_ryLGdh0zR8A$
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.ivoa.net/pipermail/dal/attachments/20241129/092e096a/attachment.htm>