<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">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 lang="EN-US" style="overflow-wrap: break-word;">
<div class="m_-6432350855774192968WordSection1">
<p class="MsoNormal">Hi Pat, DAL,<u></u><u></u></p>
<p class="MsoNormal"><u></u> <u></u></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.<u></u><u></u></p>
<p class="MsoNormal"><u></u> <u></u></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.”<u></u><u></u></i></p>
<p class="MsoNormal"><u></u> <u></u></p>
<p class="MsoNormal">That said, to mark the optional nature of the new endpoint operations, I suggest the following:<u></u><u></u></p>
<ol style="margin-top:0in" start="1" type="1">
<li class="MsoNormal">Include an <b>HTTP 501 – Not Implemented</b> response as one of the acceptable responses for the endpoint.<u></u><u></u></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.<u></u><u></u></li></ol>
<p class="MsoNormal"><u></u> <u></u></p>
<p class="MsoNormal">For example:<u></u><u></u></p>
<p class="MsoNormal"><u></u> <u></u></p>
<p class="MsoNormal" style="margin-left:0.5in">/tables:<br>
get: …<u></u><u></u></p>
<p class="MsoNormal" style="margin-left:0.5in"> put:<u></u><u></u></p>
<p class="MsoNormal" style="margin-left:0.5in"> summary: Upload a persistent table<u></u><u></u></p>
<p class="MsoNormal" style="margin-left:0.5in"> description: ><u></u><u></u></p>
<p class="MsoNormal" style="margin-left:0.5in"> This endpoint is optional and may not be implemented on all servers.<u></u><u></u></p>
<p class="MsoNormal" style="margin-left:0.5in"> If not implemented, it should return a `501 Not Implemented`.<u></u><u></u></p>
<p class="MsoNormal" style="margin-left:0.5in"> responses:<u></u><u></u></p>
<p class="MsoNormal" style="margin-left:0.5in"> '200': …<u></u><u></u></p>
<p class="MsoNormal" style="margin-left:0.5in"> '501':<u></u><u></u></p>
<p class="MsoNormal" style="margin-left:0.5in"> description: This feature is not implemented.<u></u><u></u></p>
<p class="MsoNormal"><u></u> <u></u></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.”<u></u><u></u></p>
<p class="MsoNormal"><u></u> <u></u></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.<u></u><u></u></p>
<p class="MsoNormal"><u></u> <u></u></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...<u></u><u></u></p>
<p class="MsoNormal"><u></u> <u></u></p>
<p class="MsoNormal">Thanks,<br>
Joshua Fraustro<u></u><u></u></p>
<p class="MsoNormal"><u></u> <u></u></p>
</div>
</div>
</div></blockquote></div>