<!DOCTYPE html>
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
</head>
<body>
Hi Pat, Joshua <br>
<br>
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.<br>
<br>
Then, about the status code, I have to say that I tend to prefer <i>HTTP
501 - Not implemented</i>.<br>
<br>
Firstly, because the feature is <i>really</i> 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".<br>
<br>
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.<br>
<br>
Finally, if we refer to <a
href="https://www.rfc-editor.org/rfc/rfc9110">RFC 9110</a> we have
the following texts:<br>
<br>
<blockquote>----<br>
<blockquote type="cite"><a
href="https://www.rfc-editor.org/rfc/rfc9110#name-405-method-not-allowed">15.5.6.
405 Method Not Allowed</a><br>
<br>
The 405 (Method Not Allowed) status code indicates that the
method received in the <b>request-line is known by the origin
server but not supported by the target resource.</b> The
origin server MUST generate an Allow header field in a 405
response containing a list of the target resource's currently
supported methods.</blockquote>
<br>
<blockquote type="cite"><a
href="https://www.rfc-editor.org/rfc/rfc9110#status.501">15.6.2.
501 Not Implemented</a><br>
<br>
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 <b>the server
does not recognize the request method and is not capable of
supporting it for any resource</b>.</blockquote>
<br>
<blockquote type="cite"><a
href="https://www.rfc-editor.org/rfc/rfc9110#name-overview">9.1.
Overview</a><br>
[...]<br>
<b><span
style="color: rgb(34, 34, 34); font-family: "Noto Sans", Arial, Helvetica, sans-serif; font-size: 14px; font-style: normal; font-variant-ligatures: normal; font-variant-caps: normal; letter-spacing: normal; text-align: left; text-indent: 0px; text-transform: none; word-spacing: 0px; -webkit-text-stroke-width: 0px; white-space: normal; background-color: rgb(255, 255, 255); text-decoration-thickness: initial; text-decoration-style: initial; text-decoration-color: initial; display: inline !important; float: none;">An
origin server that receives a request method that is
unrecognized <u>or</u> not implemented<span> </span></span><span
class="bcp14"
style="position: relative; font-variant: small-caps; font-size: 0.9em; color: rgb(34, 34, 34); font-family: "Noto Sans", Arial, Helvetica, sans-serif; font-style: normal; letter-spacing: normal; text-align: left; text-indent: 0px; text-transform: none; word-spacing: 0px; -webkit-text-stroke-width: 0px; white-space: normal; background-color: rgb(255, 255, 255); text-decoration-thickness: initial; text-decoration-style: initial; text-decoration-color: initial;">SHOULD</span><span
style="color: rgb(34, 34, 34); font-family: "Noto Sans", Arial, Helvetica, sans-serif; font-size: 14px; font-style: normal; font-variant-ligatures: normal; font-variant-caps: normal; letter-spacing: normal; text-align: left; text-indent: 0px; text-transform: none; word-spacing: 0px; -webkit-text-stroke-width: 0px; white-space: normal; background-color: rgb(255, 255, 255); text-decoration-thickness: initial; text-decoration-style: initial; text-decoration-color: initial; display: inline !important; float: none;"><span> </span>respond
with the<span> </span></span><a
href="https://www.rfc-editor.org/rfc/rfc9110#status.501"
class="xref"
style="text-decoration: none; z-index: 2; color: rgb(34, 34, 238); font-family: "Noto Sans", Arial, Helvetica, sans-serif; font-size: 14px; font-style: normal; font-variant-ligatures: normal; font-variant-caps: normal; letter-spacing: normal; text-align: left; text-indent: 0px; text-transform: none; word-spacing: 0px; -webkit-text-stroke-width: 0px; white-space: normal; background-color: rgb(255, 255, 255);">501
(Not Implemented)</a></b><span
style="color: rgb(34, 34, 34); font-family: "Noto Sans", Arial, Helvetica, sans-serif; font-size: 14px; font-style: normal; font-variant-ligatures: normal; font-variant-caps: normal; font-weight: 400; letter-spacing: normal; orphans: 2; text-align: left; text-indent: 0px; text-transform: none; widows: 2; word-spacing: 0px; -webkit-text-stroke-width: 0px; white-space: normal; background-color: rgb(255, 255, 255); text-decoration-thickness: initial; text-decoration-style: initial; text-decoration-color: initial; display: inline !important; float: none;"><b><span> </span></b>status
code. An origin server that receives a request method that is
recognized and implemented, but not allowed for the target
resource,<span> </span></span><span class="bcp14"
style="position: relative; font-variant: small-caps; font-weight: bold; font-size: 0.9em; color: rgb(34, 34, 34); font-family: "Noto Sans", Arial, Helvetica, sans-serif; font-style: normal; letter-spacing: normal; orphans: 2; text-align: left; text-indent: 0px; text-transform: none; widows: 2; word-spacing: 0px; -webkit-text-stroke-width: 0px; white-space: normal; background-color: rgb(255, 255, 255); text-decoration-thickness: initial; text-decoration-style: initial; text-decoration-color: initial;">SHOULD</span><span
style="color: rgb(34, 34, 34); font-family: "Noto Sans", Arial, Helvetica, sans-serif; font-size: 14px; font-style: normal; font-variant-ligatures: normal; font-variant-caps: normal; font-weight: 400; letter-spacing: normal; orphans: 2; text-align: left; text-indent: 0px; text-transform: none; widows: 2; word-spacing: 0px; -webkit-text-stroke-width: 0px; white-space: normal; background-color: rgb(255, 255, 255); text-decoration-thickness: initial; text-decoration-style: initial; text-decoration-color: initial; display: inline !important; float: none;"><span> </span>respond
with the<span> </span></span><a
href="https://www.rfc-editor.org/rfc/rfc9110#status.405"
class="xref"
style="text-decoration: none; z-index: 2; color: rgb(34, 34, 238); font-family: "Noto Sans", Arial, Helvetica, sans-serif; font-size: 14px; font-style: normal; font-variant-ligatures: normal; font-variant-caps: normal; font-weight: 400; letter-spacing: normal; orphans: 2; text-align: left; text-indent: 0px; text-transform: none; widows: 2; word-spacing: 0px; -webkit-text-stroke-width: 0px; white-space: normal; background-color: rgb(255, 255, 255);">405
(Method Not Allowed)</a><span
style="color: rgb(34, 34, 34); font-family: "Noto Sans", Arial, Helvetica, sans-serif; font-size: 14px; font-style: normal; font-variant-ligatures: normal; font-variant-caps: normal; font-weight: 400; letter-spacing: normal; orphans: 2; text-align: left; text-indent: 0px; text-transform: none; widows: 2; word-spacing: 0px; -webkit-text-stroke-width: 0px; white-space: normal; background-color: rgb(255, 255, 255); text-decoration-thickness: initial; text-decoration-style: initial; text-decoration-color: initial; display: inline !important; float: none;"><span> </span>status
code.</span><br>
</blockquote>
----<br>
</blockquote>
<br>
Both status codes do seem OK for me, but for all these reasons 501
seems to be the best match.<br>
Of course, this is my personal opinion here, so I now leave the
final decision to both of you.<br>
<br>
Cheers,<br>
Grégory M.<br>
<br>
<br>
<div class="moz-cite-prefix">On 27/11/2024 04:14, Patrick Dowler via
dal wrote:<br>
</div>
<blockquote type="cite"
cite="mid:CAFK8nrrxMfTdJAYv1dba2wDdCa=f9a=23pu-Qf4yZV7Dtc4rcA@mail.gmail.com">
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
<div dir="ltr">
<div>
<div style="font-size:small" class="gmail_default">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.</div>
<div style="font-size:small" class="gmail_default"><br>
</div>
<div style="font-size:small" class="gmail_default">I will keep
both in mind for when I get back to this.<br>
</div>
<br clear="all">
</div>
<div>
<div dir="ltr" class="gmail_signature"
data-smartmail="gmail_signature">
<div dir="ltr">
<div>
<div dir="ltr">
<div>
<div>--<br>
</div>
<div>Patrick Dowler<br>
</div>
Canadian Astronomy Data Centre<br>
</div>
Victoria, BC, Canada<br>
</div>
</div>
</div>
</div>
</div>
<br>
</div>
<br>
<div class="gmail_quote">
<div dir="ltr" class="gmail_attr">On Tue, 26 Nov 2024 at 08:10,
Joshua Fraustro <<a href="mailto:jfraustro@stsci.edu"
moz-do-not-send="true" class="moz-txt-link-freetext">jfraustro@stsci.edu</a>>
wrote:<br>
</div>
<blockquote class="gmail_quote"
style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
<div class="msg-6432350855774192968">
<div style="overflow-wrap: break-word;" lang="EN-US">
<div class="m_-6432350855774192968WordSection1">
<p class="MsoNormal">Hi Pat, DAL,</p>
<p class="MsoNormal"> </p>
<p class="MsoNormal">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.</p>
<p class="MsoNormal"> </p>
<p class="MsoNormal">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—<i>to borrow Markus’s line: “Optionality
Considered Harmful.”</i></p>
<p class="MsoNormal"> </p>
<p class="MsoNormal">That said, to mark the optional
nature of the new endpoint operations, I suggest the
following:</p>
<ol style="margin-top:0in" type="1" start="1">
<li class="MsoNormal">Include an <b>HTTP 501 – Not
Implemented</b> response as one of the acceptable
responses for the endpoint.</li>
<li class="MsoNormal">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.</li>
</ol>
<p class="MsoNormal"> </p>
<p class="MsoNormal">For example:</p>
<p class="MsoNormal"> </p>
<p class="MsoNormal" style="margin-left:0.5in">/tables:<br>
get: …</p>
<p class="MsoNormal" style="margin-left:0.5in"> put:</p>
<p class="MsoNormal" style="margin-left:0.5in">
summary: Upload a persistent table</p>
<p class="MsoNormal" style="margin-left:0.5in">
description: ></p>
<p class="MsoNormal" style="margin-left:0.5in">
This endpoint is optional and may not be implemented
on all servers.</p>
<p class="MsoNormal" style="margin-left:0.5in"> If
not implemented, it should return a `501 Not
Implemented`.</p>
<p class="MsoNormal" style="margin-left:0.5in">
responses:</p>
<p class="MsoNormal" style="margin-left:0.5in">
'200': …</p>
<p class="MsoNormal" style="margin-left:0.5in">
'501':</p>
<p class="MsoNormal" style="margin-left:0.5in">
description: This feature is not implemented.</p>
<p class="MsoNormal"> </p>
<p class="MsoNormal">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.”</p>
<p class="MsoNormal"> </p>
<p class="MsoNormal">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.</p>
<p class="MsoNormal"> </p>
<p class="MsoNormal">I hesitate to even mention it, but
another possibility would be defining an IVOA
vendor-specific extension (e.g., <i>x-optional-endpoint:
true</i>). 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...</p>
<p class="MsoNormal"> </p>
<p class="MsoNormal">Thanks,<br>
Joshua Fraustro</p>
<p class="MsoNormal"> </p>
</div>
</div>
</div>
</blockquote>
</div>
</blockquote>
<br>
</body>
</html>