[p3t] [EXTERNAL] Draft documents demonstrating standards layout

[Dave Morris]

Does Smithy have enough code generation tools ?

Looking at this list, it supports Python client, but not Java
https://github.com/smithy-lang/awesome-smithy?tab=readme-ov-file#client-code-generators

and it doesn't have either Java or Python on the server side
https://github.com/smithy-lang/awesome-smithy?tab=readme-ov-file#server-code-generators


-- Dave

--------
Dave Morris
Research Software Engineer
UK SKA Regional Centre
Department of Physics and Astronomy
University of Manchester
--------
AIMetrics: []
--------


On 2024-09-02 08:47, Paul Harrison via p3t wrote:
> On 30 Aug 2024, at 15:19, Kim Gillies <kgillies at tmt.org> wrote:
> 
> Hi All,
> 
> There is “Smithy”, which is a https://smithy.io/2.0/index.html
> [smithy.io]<https://urldefense.com/v3/__https://smithy.io/2.0/index.html__;!!PDiH4ENfjr2_Jw!C8KVmhtjHHOtHWVc6jVIK_X0IH2Jo1vI3jK0WQqnL7yxUAjled2P4rIhjtyIEOlVD8G0EO3RvOGUDrtvcbsWC_TZeg$>,
> which is similar to what is being discussed.  I do not have direct
> experience with it, and maybe it was discussed and rejected, but it is
> open source, mature, and supports many programming languages, etc.
> The following is from:
> https://smithy.io/2.0/guides/model-translations/converting-to-openapi.html
> [smithy.io]<https://urldefense.com/v3/__https://smithy.io/2.0/guides/model-translations/converting-to-openapi.html__;!!PDiH4ENfjr2_Jw!C8KVmhtjHHOtHWVc6jVIK_X0IH2Jo1vI3jK0WQqnL7yxUAjled2P4rIhjtyIEOlVD8G0EO3RvOGUDrtvcbtYFmyymQ$>
> 
> Kim
> 
> 
> 
> I think that Smithy looks pretty good- indeed it was amongst the
> alternatives suggested by the author of the oxlip interface definition
> DSL that I had mentioned when I was trying to advocate having
> something other than openAPI and the interface definition source.
> http://mail.ivoa.net/pipermail/p3t/2024-February/000031.html
> 
> It is the sort of “fully featured, and flexible” interface definition
> languages that Russ was first talking about..
> 
> The only problems are;
> 
> * The IVOA does not “own” it, so long-term is subject to the same sort
> of arguments against it that started this sub-thread looking for
> alternatives to OpenAPI
> * I am not entirely sure how to fit VO-DML (which we already have)
> into the picture with an external definition system like that. (It is
> easier to see how to use VO-DML to generate the schema part of
> OpenAPI)
> 
> Although back in February, I was not advocating writing our own
> interface DSL, I am now more inclined to think that it might the the
> best route as the argument is that we do not need something quite so
> sophisticated/flexible as a fully featured interface language if we
> have some IVOA conventions “built-in” as assumptions in our interface
> definition language.
> 
> Paul
> 
> Differences between Smithy and OpenAPI
> Smithy and OpenAPI take very different approaches to modeling APIs.
> Smithy is protocol agnostic, which means it focuses on the interfaces
> and abstractions that are provided to end-users rather than how the
> data is sent over the wire. While Smithy can define RESTful APIs, RPC
> APIs, pub/sub APIs, and more, OpenAPI only defines RESTful APIs. Both
> approaches have their own strengths and weaknesses. For example, while
> Smithy can define a much broader set of functionality, services, and
> client behaviors, it requires abstractions that have their own
> underlying complexity. OpenAPI is more permissive in the kinds of
> services it can describe, making it easier to adapt to existing web
> services, but at the same time making it easier to author APIs that
> provide a poor customer experience when using clients in
> strongly-typed languages.
> 
> On Aug 30, 2024, at 4:04 AM, Paul Harrison via p3t
> <p3t at ivoa.net<mailto:p3t at ivoa.net>> wrote:
> 
> 
> 
> On 29 Aug 2024, at 18:59, Russ Allbery <eagle at eyrie.org> wrote:
> 
> 
> My larger concern is that I am dubious that OpenAPI will prove to be
> resilient against future changes to prevailing protocols and definition
> languages any more than XML schemas were.  gRPC does not use OpenAPI, 
> for
> example; it uses protobuf as its API definition language.  I fear that
> OpenAPI is a specification language for this one particular moment in
> time, and in the future people will use something else, similar to how 
> XML
> schemas used to be common and now, although they still exist, they're 
> less
> widely used.
> 
> That said, designing a specification language is an immense amount of
> work, and I don't want us to write our own either.  We should use 
> OpenAPI
> today because that's what people use today.  But I would like to have 
> some
> sort of semantic language specific to the IVOA, ideally one with a 
> minimum
> amount of additional formality so that it's easy to read and easy to
> write, that nails down all the things that OpenAPI may leave ambiguous 
> and
> provides enough additional information that we can adapt our data types 
> to
> some new language that comes along later.
> 
> 
> 
> Designing a general purpose specification language is a lot of work -
> however, all we *need* is a language to describe
> interfaces that follow IVOA patterns, so that it does not have to be
> that extensive. So for example when the
> hypothetical IVOA interface language says for example “return error”
> it can be transformed into the IVOA pattern in OpenAPI that
> expresses the way to return an error. So that a lot of the “detail”
> that makes OpenAPI complex is removed by having conventions.
> 
> Paul.
> 
> --
> p3t mailing list
> p3t at ivoa.net
> http://mail.ivoa.net/mailman/listinfo/p3t
> [mail.ivoa.net]<https://urldefense.com/v3/__http://mail.ivoa.net/mailman/listinfo/p3t__;!!PDiH4ENfjr2_Jw!C8KVmhtjHHOtHWVc6jVIK_X0IH2Jo1vI3jK0WQqnL7yxUAjled2P4rIhjtyIEOlVD8G0EO3RvOGUDrtvcbuhP8tH-Q$>