<html xmlns:o="urn:schemas-microsoft-com:office:office" xmlns:w="urn:schemas-microsoft-com:office:word" xmlns:m="http://schemas.microsoft.com/office/2004/12/omml" xmlns="http://www.w3.org/TR/REC-html40">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<meta name="Generator" content="Microsoft Word 15 (filtered medium)">
<style><!--
/* Font Definitions */
@font-face
{font-family:"Cambria Math";
panose-1:2 4 5 3 5 4 6 3 2 4;}
@font-face
{font-family:Calibri;
panose-1:2 15 5 2 2 2 4 3 2 4;}
/* Style Definitions */
p.MsoNormal, li.MsoNormal, div.MsoNormal
{margin:0in;
font-size:11.0pt;
font-family:"Calibri",sans-serif;
mso-ligatures:standardcontextual;}
span.EmailStyle17
{mso-style-type:personal-compose;
font-family:"Calibri",sans-serif;
color:windowtext;}
.MsoChpDefault
{mso-style-type:export-only;}
@page WordSection1
{size:8.5in 11.0in;
margin:1.0in 1.0in 1.0in 1.0in;}
div.WordSection1
{page:WordSection1;}
/* List Definitions */
@list l0
{mso-list-id:818695191;
mso-list-type:hybrid;
mso-list-template-ids:-1843919504 67698703 67698713 67698715 67698703 67698713 67698715 67698703 67698713 67698715;}
@list l0:level1
{mso-level-tab-stop:none;
mso-level-number-position:left;
text-indent:-.25in;}
@list l0:level2
{mso-level-number-format:alpha-lower;
mso-level-tab-stop:none;
mso-level-number-position:left;
text-indent:-.25in;}
@list l0:level3
{mso-level-number-format:roman-lower;
mso-level-tab-stop:none;
mso-level-number-position:right;
text-indent:-9.0pt;}
@list l0:level4
{mso-level-tab-stop:none;
mso-level-number-position:left;
text-indent:-.25in;}
@list l0:level5
{mso-level-number-format:alpha-lower;
mso-level-tab-stop:none;
mso-level-number-position:left;
text-indent:-.25in;}
@list l0:level6
{mso-level-number-format:roman-lower;
mso-level-tab-stop:none;
mso-level-number-position:right;
text-indent:-9.0pt;}
@list l0:level7
{mso-level-tab-stop:none;
mso-level-number-position:left;
text-indent:-.25in;}
@list l0:level8
{mso-level-number-format:alpha-lower;
mso-level-tab-stop:none;
mso-level-number-position:left;
text-indent:-.25in;}
@list l0:level9
{mso-level-number-format:roman-lower;
mso-level-tab-stop:none;
mso-level-number-position:right;
text-indent:-9.0pt;}
@list l1
{mso-list-id:1301184137;
mso-list-template-ids:874291478;}
@list l2
{mso-list-id:1866675565;
mso-list-template-ids:-1090372610;}
@list l2:level1
{mso-level-tab-stop:.5in;
mso-level-number-position:left;
text-indent:-.25in;}
@list l2:level2
{mso-level-tab-stop:1.0in;
mso-level-number-position:left;
text-indent:-.25in;}
@list l2:level3
{mso-level-tab-stop:1.5in;
mso-level-number-position:left;
text-indent:-.25in;}
@list l2:level4
{mso-level-tab-stop:2.0in;
mso-level-number-position:left;
text-indent:-.25in;}
@list l2:level5
{mso-level-tab-stop:2.5in;
mso-level-number-position:left;
text-indent:-.25in;}
@list l2:level6
{mso-level-tab-stop:3.0in;
mso-level-number-position:left;
text-indent:-.25in;}
@list l2:level7
{mso-level-tab-stop:3.5in;
mso-level-number-position:left;
text-indent:-.25in;}
@list l2:level8
{mso-level-tab-stop:4.0in;
mso-level-number-position:left;
text-indent:-.25in;}
@list l2:level9
{mso-level-tab-stop:4.5in;
mso-level-number-position:left;
text-indent:-.25in;}
ol
{margin-bottom:0in;}
ul
{margin-bottom:0in;}
--></style>
</head>
<body lang="EN-US" link="#0563C1" vlink="#954F72" style="word-wrap:break-word">
<div class="WordSection1">
<p class="MsoNormal">Hi Pat, DAL,<o:p></o:p></p>
<p class="MsoNormal"><o:p> </o:p></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.<o:p></o:p></p>
<p class="MsoNormal"><o:p> </o:p></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.”<o:p></o:p></i></p>
<p class="MsoNormal"><o:p> </o:p></p>
<p class="MsoNormal">That said, to mark the optional nature of the new endpoint operations, I suggest the following:<o:p></o:p></p>
<ol style="margin-top:0in" start="1" type="1">
<li class="MsoNormal" style="mso-list:l1 level1 lfo3">Include an <b>HTTP 501 – Not Implemented</b> response as one of the acceptable responses for the endpoint.<o:p></o:p></li><li class="MsoNormal" style="mso-list:l1 level1 lfo3">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.<o:p></o:p></li></ol>
<p class="MsoNormal"><o:p> </o:p></p>
<p class="MsoNormal">For example:<o:p></o:p></p>
<p class="MsoNormal"><o:p> </o:p></p>
<p class="MsoNormal" style="margin-left:.5in">/tables:<br>
get: …<o:p></o:p></p>
<p class="MsoNormal" style="margin-left:.5in"> put:<o:p></o:p></p>
<p class="MsoNormal" style="margin-left:.5in"> summary: Upload a persistent table<o:p></o:p></p>
<p class="MsoNormal" style="margin-left:.5in"> description: ><o:p></o:p></p>
<p class="MsoNormal" style="margin-left:.5in"> This endpoint is optional and may not be implemented on all servers.<o:p></o:p></p>
<p class="MsoNormal" style="margin-left:.5in"> If not implemented, it should return a `501 Not Implemented`.<o:p></o:p></p>
<p class="MsoNormal" style="margin-left:.5in"> responses:<o:p></o:p></p>
<p class="MsoNormal" style="margin-left:.5in"> '200': …<o:p></o:p></p>
<p class="MsoNormal" style="margin-left:.5in"> '501':<o:p></o:p></p>
<p class="MsoNormal" style="margin-left:.5in"> description: This feature is not implemented.<o:p></o:p></p>
<p class="MsoNormal"><o:p> </o:p></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.”<o:p></o:p></p>
<p class="MsoNormal"><o:p> </o:p></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.<o:p></o:p></p>
<p class="MsoNormal"><o:p> </o:p></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...<o:p></o:p></p>
<p class="MsoNormal"><o:p> </o:p></p>
<p class="MsoNormal">Thanks,<br>
Joshua Fraustro<o:p></o:p></p>
<p class="MsoNormal"><o:p> </o:p></p>
</div>
</body>
</html>