[p3t] Simple Cone Search starting point added

[Gregory MANTELET]

Hello,

Thank you for this starting point. It will certainly be very useful, as 
you say, to quickly iterate.

FYI, the Cone Search service of SIMBAD provides an OpenAPI document and 
a Swagger interface.

  * Swagger interface: https://simbad.cds.unistra.fr/cone/help/

  * OpenAPI document (in YAML): https://simbad.cds.unistra.fr/cone/openapi

  * OpenAPI document (in JSON ; only with Accept: application/json):

        *wget* /--header "Accept: application/json"/
        'https://simbad.cds.unistra.fr/cone/openapi'


Compared to the current stable version of the Cone Search 
recommendation, we have added more parameters, but the basic one are there.

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.

Cheers,
Grégory M.


On 20/02/2024 19:33, Russ Allbery wrote:
> I have added a starting point for looking at an OpenAPI schema for Simple
> Cone Search. README is available at:
>
>      https://github.com/ivoa/PTTT/tree/main/cone-search
>
> 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.
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.ivoa.net/pipermail/p3t/attachments/20240222/4834d336/attachment.htm>