
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">

<html>

<body>

<div dir="auto">

<div dir="auto"><br></div>Yes, I agree.<div dir="auto">More later when I find WiFi for laptop.<br><div dir="auto"><br></div>

<div id="aqm-original" style="color: black;">

<div dir="auto">On 26 February 2024 16:56:38 Joshua Fraustro via p3t <p3t@ivoa.net> wrote:</div>

<div><br></div>

<blockquote type="cite" class="gmail_quote" style="margin: 0 0 0 0.75ex; border-left: 1px solid #808080; padding-left: 0.75ex;">

<div dir="auto">Hi,</div>

<div dir="auto"><br></div>

<div dir="auto">As others have pointed out, the OpenAPI specification I wrote for UWS in the Space Telescope repo below was written by hand, from the UWS standard. It was partly guided by the work done in FastAPI for our TAP service, but was written whole-cloth using the UWS document as the ultimate source of truth (which came with all the difficulties of parsing that document I have often complained about).</div>

<div dir="auto"><br></div>

<div dir="auto">https://github.com/spacetelescope/vo-openapi</div>

<div dir="auto"><br></div>

<div dir="auto">I like the repository structure you've given and I'd be happy to move this work to the IVOA repo, with the understanding that this is not the definitive version of the document, but maybe something just informative.</div>

<div dir="auto"><br></div>

<div dir="auto">As you mentioned Dave, I did find writing it in JSON to be somewhat distasteful, and despite some of my gripes with the YAML syntax, it is much more readable in my opinion.</div>

<div dir="auto"><br></div>

<div dir="auto">I would also strongly advocate for Dave's 'contract-first' approach. The following is mostly in response to your last few paragraphs, Dave-- your comment of everyone being happier with their existing tools and not using OpenAPI to generate code for their services (though I know you're not actually suggesting that) made me somewhat anxious that we might lose sight of what I see is real benefit of this work.</div>

<div dir="auto"><br></div>

<div dir="auto">~~ Jumping on the soapbox here ~~</div>

<div dir="auto"><br></div>

<div dir="auto">What I view as the most important product of all of this: a way to clear, concise, and (importantly) technical way define standards-- a 'thing' that describes the standard and nothing but the standard. You send this payload to that endpoint, and you'll get this response. All the wonderful benefits of using the OpenAPI tooling, generating code, validating, etc. are just icing on the cake.</div>

<div dir="auto"><br></div>

<div dir="auto">When I think about the IVOA, I'm looking at it as just an engineer. With this group specifically, I'm putting myself in the shoes of an engineer, who just had the request to create a TAP service dropped on their lap, who has no prior knowledge that something like the IVOA even existed (which is exactly what happened to me). Consider also, and I'll say the uncomfortable part out loud, an engineer who might not actually care all much about VO standards, and just needs to write a service that passes validation before he clocks out and gets to stop thinking about it. Considering that scenario, that's where all the usefulness of OpenAPI documents (and this work more generally) will come out:</div>

<div dir="auto"><br></div>

<div dir="auto">1. A small team could, yes, just opt to use the OpenAPI spec to generate a server, plug their machinery in and be done with it. They don't need even need to look too closely at the OpenAPI spec, except to know what the data is that they want to send.</div>

<div dir="auto">2. Maybe there is no code generator for my particular language, but I can look at it and write my own server, and I know that it will be compliant with the standard. X endpoint, Y payload, Z response.</div>

<div dir="auto">3. No ambiguity. No, "this other client interprets things this way, so we have to do it that way too." No, "This has been historically understood as..." No, "Well, the way I interpret this paragraph is.." and maybe my biggest gripe: "This behavior is fully described by (some other standard)."</div>

<div dir="auto"><br></div>

<div dir="auto">~~ done with the preaching ~~</div>

<div dir="auto"><br></div>

<div dir="auto">I know this isn't ~directly~ following the chain of the thread here, but it's what's been in my mind following the various threads thus far.</div>

<div dir="auto"><br></div>

<div dir="auto"><br></div>

<div dir="auto"><br></div>

<div dir="auto">?On 2/25/24, 11:47 PM, "p3t on behalf of Dave Morris via p3t" <p3t-bounces@ivoa.net <mailto:p3t-bounces@ivoa.net> on behalf of p3t@ivoa.net <mailto:p3t@ivoa.net>> wrote:</div>

<div dir="auto"><br></div>

<div dir="auto"><br></div>

<div dir="auto">External Email - Use Caution</div>

<div dir="auto"><br></div>

<div dir="auto"><br></div>

<div dir="auto">Hiya,</div>

<div dir="auto"><br></div>

<div dir="auto"><br></div>

<div dir="auto">Can we jump back a bit and just check what the aim of the pt3 team is.</div>

<div dir="auto"><br></div>

<div dir="auto"><br></div>

<div dir="auto">As I understood it, the aim of the team was to evaluate how to make the</div>

<div dir="auto">IVOA services compatible with new tools and frameworks like OpenAPI,</div>

<div dir="auto">FastAPI and Spring. Identify the legacy issues that make it hard to</div>

<div dir="auto">implement our services using these tools, and make recommendations on</div>

<div dir="auto">how best to develop the next generation of our services.</div>

<div dir="auto"><br></div>

<div dir="auto"><br></div>

<div dir="auto">I'm not sure we have the remit to design the next generation cone-search</div>

<div dir="auto">and UWS here. I'd have though that would be up to the DAL and GWS</div>

<div dir="auto">working groups to build on the recommendations that come from this team</div>

<div dir="auto">to help them develop the next generation of their services.</div>

<div dir="auto"><br></div>

<div dir="auto"><br></div>

<div dir="auto">Anyway, I'd like to leave the details of the cone-search and UWS</div>

<div dir="auto">improvements for a moment and concentrate on the evaluating the new</div>

<div dir="auto">tools and processes part. In particular, this email is about how and why</div>

<div dir="auto">we want to use OpenAPI.</div>

<div dir="auto"><br></div>

<div dir="auto"><br></div>

<div dir="auto">From what I understand the current contribution from Russ uses Python</div>

<div dir="auto">and the FastAPI framework to generate the service description. The</div>

<div dir="auto">service is defined by the Python code and the OpenAPI definition is</div>

<div dir="auto">reverse engineered from that.</div>

<div dir="auto"><br></div>

<div dir="auto"><br></div>

<div dir="auto">I'm not clear how this would be applicable in the context of the IVOA,</div>

<div dir="auto">where we are explicitly designing standards to work across a</div>

<div dir="auto">heterogeneous environment of different programming languages and</div>

<div dir="auto">frameworks.</div>

<div dir="auto"><br></div>

<div dir="auto"><br></div>

<div dir="auto">Where OpenAPI descriptions may be able to help us develop interoperable</div>

<div dir="auto">specifications is if we work "contract first". Starting with the OpenAPI</div>

<div dir="auto">definition, included as part of the standard document, and then each</div>

<div dir="auto">group could use the machine readable definition to generate or validate</div>

<div dir="auto">their implementations.</div>

<div dir="auto"><br></div>

<div dir="auto"><br></div>

<div dir="auto">Now that Russ has given us an initial OpenAPI description for</div>

<div dir="auto">cone-search, I'd like to see if we change direction of the process and</div>

<div dir="auto">generate our service implementations from the OpenAPI description.</div>

<div dir="auto"><br></div>

<div dir="auto"><br></div>

<div dir="auto">With this in mind I would like to add a number of directory levels at</div>

<div dir="auto">the top of the project repository.</div>

<div dir="auto"><br></div>

<div dir="auto"><br></div>

<div dir="auto">First, I would separate the specification from the implementations,</div>

<div dir="auto">placing the openapi.json contract in a separate 'ivoa' directory at the</div>

<div dir="auto">top of the project. Making it clear that this is the interoperable part</div>

<div dir="auto">that would be provided as part of the IVOA standard.</div>

<div dir="auto"><br></div>

<div dir="auto"><br></div>

<div dir="auto">cone-search</div>

<div dir="auto">ivoa</div>

<div dir="auto">openapi.json</div>

<div dir="auto">impl</div>

<div dir="auto">....</div>

<div dir="auto"><br></div>

<div dir="auto"><br></div>

<div dir="auto">A number of people have commented on the readability and maintainability</div>

<div dir="auto">of the JSON version of the OpenAPI description. In which case, perhaps</div>

<div dir="auto">it would be better to start with the YAML version.</div>

<div dir="auto"><br></div>

<div dir="auto"><br></div>

<div dir="auto">cone-search</div>

<div dir="auto">ivoa</div>

<div dir="auto">openapi.yaml</div>

<div dir="auto">impl</div>

<div dir="auto">....</div>

<div dir="auto"><br></div>

<div dir="auto"><br></div>

<div dir="auto">Then, within the implementations, I would add a separation based on</div>

<div dir="auto">languages and framework.</div>

<div dir="auto"><br></div>

<div dir="auto"><br></div>

<div dir="auto">cone-search</div>

<div dir="auto">ivoa</div>

<div dir="auto">openapi.yaml</div>

<div dir="auto">impl</div>

<div dir="auto">python</div>

<div dir="auto">fastapi</div>

<div dir="auto">....</div>

<div dir="auto">java</div>

<div dir="auto">spring</div>

<div dir="auto">....</div>

<div dir="auto"><br></div>

<div dir="auto"><br></div>

<div dir="auto">This enables others to add implementations using their favourite</div>

<div dir="auto">frameworks and languages.</div>

<div dir="auto"><br></div>

<div dir="auto"><br></div>

<div dir="auto">I would be willing to volunteer to develop a Java based implementation</div>

<div dir="auto">using the Spring framework.</div>

<div dir="auto"><br></div>

<div dir="auto"><br></div>

<div dir="auto">It would be interesting to see if we could get volunteers to have a go</div>

<div dir="auto">at developing similar implementations using Rust or Go.</div>

<div dir="auto"><br></div>

<div dir="auto"><br></div>

<div dir="auto">Note that the Python FastAPI implementation here would be the reverse of</div>

<div dir="auto">the one currently provided by Russ. It would start with the OpenAPI</div>

<div dir="auto">description and use the FastAPI framework to auto-generate the service</div>

<div dir="auto">implementation Python classes from the OpenAPI description.</div>

<div dir="auto"><br></div>

<div dir="auto"><br></div>

<div dir="auto">To make this clearer we could add a further level of distinction between</div>

<div dir="auto">the forward process, starting with the OpenAPI definition and generating</div>

<div dir="auto">the implementation classes, and the reverse process, starting with the</div>

<div dir="auto">implementation classes and auto-generating the OpenAPI definition.</div>

<div dir="auto"><br></div>

<div dir="auto"><br></div>

<div dir="auto">cone-search</div>

<div dir="auto">ivoa</div>

<div dir="auto">openapi.yaml</div>

<div dir="auto">impl</div>

<div dir="auto">python</div>

<div dir="auto">fastapi</div>

<div dir="auto">forward</div>

<div dir="auto"># OpenAPI -> auto-generated Python</div>

<div dir="auto">reverse</div>

<div dir="auto"># Python -> auto-generated OpenAPI (Russ's</div>

<div dir="auto">current code)</div>

<div dir="auto">java</div>

<div dir="auto">spring</div>

<div dir="auto">forward</div>

<div dir="auto"># OpenAPI -> auto-generated Java</div>

<div dir="auto">reverse</div>

<div dir="auto"># Java -> auto-generated OpenAPI</div>

<div dir="auto"><br></div>

<div dir="auto"><br></div>

<div dir="auto"><br></div>

<div dir="auto"><br></div>

<div dir="auto">Once we have at least 2 forward implementations that start "contract</div>

<div dir="auto">first" from the OpenAPI description and generate the implementation</div>

<div dir="auto">classes from it, then we would be able to evaluate if including the</div>

<div dir="auto">machine readable OpenAPI description of the service is a useful addition</div>

<div dir="auto">that helps in developing interoperable services.</div>

<div dir="auto"><br></div>

<div dir="auto"><br></div>

<div dir="auto">It is interesting to note that Gregory also has cone-search</div>

<div dir="auto">implementation that is able to provide OpenAPI and Swagger descriptions</div>

<div dir="auto">of their service, but so far no one has said that they started with an</div>

<div dir="auto">OpenAPI description and generated their implementation from it.</div>

<div dir="auto"><br></div>

<div dir="auto"><br></div>

<div dir="auto">If it turns out that everyone is happier developing their code using</div>

<div dir="auto">their existing tools, without auto-generating the classes from an</div>

<div dir="auto">OpenAPI description, then this would suggest that providing an OpenAPI</div>

<div dir="auto">definition as part of our standards might not be as useful as we first</div>

<div dir="auto">thought.</div>

<div dir="auto"><br></div>

<div dir="auto"><br></div>

<div dir="auto">Historical note - the same thing happened with WSDL. Everyone said it</div>

<div dir="auto">was the "next best thing", but in the end, no one actually used it to</div>

<div dir="auto">generate code for their services.</div>

<div dir="auto"><br></div>

<div dir="auto"><br></div>

<div dir="auto">The resulting code was just too fragile.</div>

<div dir="auto"><br></div>

<div dir="auto"><br></div>

<div dir="auto">Looking forward to the discussion.</div>

<div dir="auto"><br></div>

<div dir="auto"><br></div>

<div dir="auto">-- Dave</div>

<div dir="auto"><br></div>

<div dir="auto"><br></div>

<div dir="auto">--------</div>

<div dir="auto">Dave Morris</div>

<div dir="auto">Research Software Engineer</div>

<div dir="auto">Wide Field Astronomy Unit</div>

<div dir="auto">Institute for Astronomy</div>

<div dir="auto">University of Edinburgh</div>

<div dir="auto">--------</div>

<div dir="auto">AIMetrics: [{"name": "*","contribution": {"value": 0,"units": "%"}}]</div>

<div dir="auto">--------</div>

<div dir="auto">--</div>

<div dir="auto">p3t mailing list</div>

<div dir="auto">p3t@ivoa.net <mailto:p3t@ivoa.net></div>

<div dir="auto">https://urldefense.com/v3/__http://mail.ivoa.net/mailman/listinfo/p3t__;!!CrWY41Z8OgsX0i-WU-0LuAcUu2o!waPXMrWFO_L7ZtnVai8Vh29AiMJSnl4laf2lgvNv4prS7i10jsWrqaFFW1hSk8cbu2QoE7HGJ0o$ <https://urldefense.com/v3/__http://mail.ivoa.net/mailman/listinfo/p3t__;!!CrWY41Z8OgsX0i-WU-0LuAcUu2o!waPXMrWFO_L7ZtnVai8Vh29AiMJSnl4laf2lgvNv4prS7i10jsWrqaFFW1hSk8cbu2QoE7HGJ0o$></div>

<div dir="auto"><br></div>

<div dir="auto"><br></div>

<div dir="auto"><br></div>

<div dir="auto">-- </div>

<div dir="auto">p3t mailing list</div>

<div dir="auto">p3t@ivoa.net</div>

<div dir="auto">http://mail.ivoa.net/mailman/listinfo/p3t</div>

</blockquote>

</div><div dir="auto"><br></div>

</div>

</div>

<div style="color: black;">

<p style="margin: 0 0 1em 0; color: black; font-family: sans-serif;"><br>

Sent with <a href="https://link.aqua-mail.com/dl/signature">Aqua Mail for Android</a></p>

</div>

</body>

</html>