<!DOCTYPE html>
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
</head>
<body>
Hello,<br>
<br>
Thank you for this starting point. It will certainly be very useful,
as you say, to quickly iterate.<br>
<br>
FYI, the Cone Search service of SIMBAD provides an OpenAPI document
and a Swagger interface.<br>
<br>
<ul>
<li>Swagger interface: <a
href="https://simbad.cds.unistra.fr/cone/help/"
class="moz-txt-link-freetext">https://simbad.cds.unistra.fr/cone/help/</a></li>
</ul>
<ul>
<li>OpenAPI document (in YAML): <a
href="https://simbad.cds.unistra.fr/cone/openapi"
class="moz-txt-link-freetext">https://simbad.cds.unistra.fr/cone/openapi</a></li>
</ul>
<ul>
<li>OpenAPI document (in JSON ; only with Accept:
application/json):</li>
</ul>
<blockquote>
<blockquote> <font face="monospace"><b>wget</b> <i>--header
"Accept: application/json"</i>
'<a class="moz-txt-link-freetext" href="https://simbad.cds.unistra.fr/cone/openapi">https://simbad.cds.unistra.fr/cone/openapi</a>'</font><br>
</blockquote>
</blockquote>
<br>
Compared to the current stable version of the Cone Search
recommendation, we have added more parameters, but the basic one are
there.<br>
<br>
Anyway, it could be interesting to compare both OpenAPI documents. I
had not taken the time yet to do so, but I may in some days.<br>
<br>
Cheers,<br>
Grégory M.<br>
<br>
<br>
<div class="moz-cite-prefix">On 20/02/2024 19:33, Russ Allbery
wrote:<br>
</div>
<blockquote type="cite" cite="mid:87frxnugsk.fsf@hope.eyrie.org">
<pre class="moz-quote-pre" wrap="">I have added a starting point for looking at an OpenAPI schema for Simple
Cone Search. README is available at:
<a class="moz-txt-link-freetext" href="https://github.com/ivoa/PTTT/tree/main/cone-search">https://github.com/ivoa/PTTT/tree/main/cone-search</a>
This is mostly a framework to get started and let us quickly iterate on
the OpenAPI schema by letting FastAPI do most of the work. I focused on
getting the framework in place rather than adding a lot of API details.
This provides only a sync GET interface without capabilities or
availability. For a more fully-fleshed example, we'll want to add an async
interface with UWS and models for capabilities and availability. I plan on
working on that next if this is a suitable starting point.
Some additional notes and cautions:
* FastAPI is not an ideal OpenAPI schema generator, and I suspect it will
not generate exactly the schema that we would want. Please consider this
only a proof-of-concept for fast iteration. An OpenAPI schema suitable
for publication would likely require some additional manual tweaking.
* FastAPI makes documentation available with both Swagger and Redoc. Both
of them have their quirks, but they're both useful renderers for human
browsing. I personally prefer Redoc, but I encourage folks to try
both. Swagger has a bug that causes it to double-escape the example
VOTable response. This appears to be rendered correctly in Redoc.
* Apologies for the giant blob of XML that's awkwardly encoded in the JSON
file. I wanted to show how XML responses can be documented, but the
resulting JSON is pretty ugly.
* The error model is a quick hack based on the errors that FastAPI
produces by default, including the 422 error code that FastAPI likes to
use for requests that fail schema validation. This is probably not the
exact error model that we want. I threw it in there so that people could
see how we could define structured errors, not to propose this specific
structured error format as the best one (although it is convenient in
Python since FastAPI generates it by default). We will probably also
want to document some additional error codes (at least 401 and 403).
Let me know if you have any comments, questions, or problems following the
README.
</pre>
</blockquote>
<br>
</body>
</html>