[p3t] Simple Cone Search starting point added

[Russ Allbery]

Paul Harrison <paul.harrison at manchester.ac.uk> writes:

> I fully understand the desire not to write OpenAPI definitions directly,
> as they are difficult for humans to parse and quickly become very large
> for reasonably sized services - (Though I note that Joshua has
> apparently handwritten these
> https://github.com/spacetelescope/vo-openapi/tree/main/openapi/uws) - I
> think that we should find a ‘neutral’ way of expressing the 'source
> code' for creating the definitions. We do already have an IVOA endorsed
> solution that has been created for the “schema” part- i.e. VO-DML that
> should be used, even if the “interface” part is generated in some other
> fashion (or hand written).

I think maintaining them directly in YAML would be fine, and then using
YAML to convert to JSON.  The main reasons why I'm starting with the
FastAPI autogenerated ones is just that (a) I'm very familiar with FastAPI
so it takes me about half the time to write a Pydantic model or a handler
signature than look up the OpenAPI equivalent, which only applies to this
rapid prototyping phase, and (b) I get integration with Swagger and Redoc
for "free" without having to figure out how to point them at an arbitrary
schema, and I think the human-readable documentation is a nice way to
explore the schema.

I'm fairly sure that if we find something we mostly like by iterating on
the FastAPI approach, we can just take that output, convert it to YAML for
ease of human maintenance over JSON, and do an editing pass and have a
reasonable start at a manually-maintained schema.

> We also need to put in place some linting/testing/code generation
> facilities against the definitions in several different languages to
> make sure that we are not doing anything that does not have widespread
> support.

Yes, agreed.  I know those tools are out there, but I've personally not
used them.  That would be a great thing for someone else to take a look
at.

> On 21 Feb 2024, at 10:18, Molinaro, Marco <marco.molinaro at inaf.it> wrote:

>> I wonder if it's better to stick to the current
>> ConeSearch-1.03, which has no POST.
>> I'd like this discussed too.

> I think that we discussed at the last meeting that we had the freedom to
> produce v2.0 services that were incompatible with the previous versions
> - however, I think that if we are going to do this then we might as well
> be more radical and produce a new “Data access service” that encompasses
> all of what SCS SIAP and SSAP in a single service definition.

I also wanted to mention that my main goal for our next meeting is to
produce a relatively complex schema including UWS support for an IVOA
service, so that we can talk through the details.  I think *which* IVOA
service is somewhat irrelevant for the part of the discussion that's about
the general principles of protocol and schema, and Simple Cone Search is
just a convenient simple one.  But for example I will add UWS support even
if that isn't a priority for Simple Cone Search since we know we'll want
UWS support for other things, and will probably add POST for similar
reasons.  That doesn't mean I think we should really add those things to
Simple Cone Search, just that I need some convenient protocol to show what
a JSON-based schema could be like.

-- 
Russ Allbery (eagle at eyrie.org)             <https://www.eyrie.org/~eagle/>