SDK IDL should use a portable format

[mattheworiordan]

If we use a portable definition language for our SDK interfaces and types, we benefit from potentially being able to autogenerate code in languages we support.

Currently our IDL uses a bespoke format which was intentional to avoid coupling to any language idiomatic features, however this approach too has its shortcomings. See @SimonWoolf thoughts on this at #48.

---

Extracts from a Slack convo

Matt

Whilst talking to the folks at AsyncAPI they said they are looking at using Quicktype to auto-generate types that they can use in their generated SDKs. I tried our TypeScript definition and created https://app.quicktype.io?share=BOtw8DjRdmLMIT9cLCy0

It got me thinking though:

• Could we use this (manually) to take the client lib spec in a format like TypeScript and generate types across all our SDKs?
• Given the serialisation problems we’ve just had with Dart / Flutter, could we use it there too to help avoid typos etc?

Simon

That does look neat.
The generator is giving not-great output for the pseudo-enums in the ably-js typings (which I think might have been originally written by someone before typescript had enums, and we've stuck with that style since) -- we'd write cleaned-up typings, maybe in a subset of typescript that gives decent results with quicktype.
I suspect it wouldn't ever be quite good enough to autogenerate and use unmodified, just as a starting point. especially since some libs do depart from the standard typings in deliberate/limited ways, eg for callbacks vs promises vs sync functions per what's idiomatic in the language.
Anyway, main point is 👍 to using consistent machine-readable typescript for our IDL, rather than the almost-rust-ish pseudocode we have now. (Which is actually something I've proposed previously - #48 )

┆Issue is synchronized with this Jira Task by Unito

[QuintinWillison]

Related is my comment here: #48

[QuintinWillison]

See also #47

[QuintinWillison]

@lmars has suggested a possible contender could be AWS' Smithy.

[lmars]

One issue I have with the current IDL is that it tries to cover both types and method calls, and whilst we can expect types to be quite portable across languages, being prescriptive about methods and calling conventions often leads to non-idiomatic code across our SDKs.

[sync-by-unito]

➤ Automation for Jira commented:

The link to the corresponding Jira issue is https://ably.atlassian.net/browse/SDK-2784