[Discussion] Best practices for an interoperable, documented surface area

[kofalt]

Hi! Great project, I'm using it for single-digit-ms RPC in anger and loving it.

Right now, I am using nexus to speak from & to Go clients which I control, but that situation will soon be changing. I make fairly simple assumptions on the data types that come across the wire, and these assumptions are hard-coded into the clients. This does not make integrating from another language, or a codebase I don't control, obvious or intuitive.

With a REST-ish HTTP API, the answer is fairly self-evident: grab something like OpenAPI, fill out some YAML, and you probably find something to render HTML docs or a Go library to parse and validate your docs. Obviously, I don't need that level of polish, but I'm not sure where to start.

With WAMP, it's not super clear to me how to:

• Make a surface area discoverable
• Establish a language-agnostic way to describe types on a call
• Cleanly validate args/kwargs when called

What have nexus users done? What's worked, what hasn't? 🙂

[martin31821]

You can see a bit of discussion here; #165. We're still working on this.

[kofalt]

Interesting - I'll leave this open for others to add their ideas / questions and possibly update with my own approach. I like the testing discussion but am also focused on easily consuming endpoints from other languages.

Some inspiration: Varlink uses discoverable and self-documenting files that are similar in nature to the example you link. The idea that you can just ask a Varlink server what it does, and quickly understand everything you need to consume its functionality, is pretty slick.

[martin31821]

I think it might be interesting to experiment with code generation from a spec file, and I also know there's a feature proposal to add reflection as meta api, maybe it can be extended to Include schema information.. Just a thought.

Please take a look in the HA issue in nexus, where we already discussed some approaches for external/internal api schemes