Purpose of Endpoint and other microservice stuff

[Kinrany]

What is the purpose of creating an Endpoint value?

I couldn't find any docs. It can't be used to handle requests, only to stop() something, which is also undocumented.

I suppose this is partly an issue of docs.nats.io saying very little about all this, despite nats micro being a thing.

[Jarema]

docs.nats.io are about general concepts, not language specific ones.
To learn more about language-specific API, please refer each library docs.
You can see there, that Endpoint also implements Stream, which allows you for iterating over messages in it.

I will update the docs for more examples soon.

[Kinrany]

You can see there, that Endpoint also implements Stream, which allows you for iterating over messages in it.

Ah, that makes sense. Thanks! I didn't think of looking at the list of impls.

docs.nats.io are about general concepts, not language specific ones.

Are endpoints a Rust-only concept?

Services are a general concept for sure, right? Since the NATS service and the CLI do know about them? This is something that keeps confusing me 🤔

[Jarema]

Endpoints are not Rust only concept. In each client you can create an emdpoints, groups, etc. Of course the Endpoint implementaion details and usage is Rust-specific :).

[Kinrany]

That makes sense too. So normally, as a language specific implementation of a general concept, the docs would include at most a brief description of the general concept and refer to the main docs, and then document only the language-specific implementation details. Right?

What is the best place to petition for documenting the service concepts on docs.nats.io? 😄

[Jarema]

Almost.

Language specific docs should be exhaustive and show usage, but they do not have to explain general NATS concepts, topologies, etc.

We are now working hard on new docs that would have this split much clearer and refer back and forth links between API docs and general docs, so no need to open petition for this specificaly :).

There are also ADRs, which are a great reference points for design: https://github.com/nats-io/nats-architecture-and-design/blob/main/adr/ADR-32.md