Taking this a bit further, it's surprising how many companies sell API as a service but provide minimal support for that API, publishing like 1 client/sdk (and often not in the language you need, lol).
Just mindblowing that companies don't adopt a schema-first approach to appeal to a broader customer base. I've lost count of the number of hnd rolled clients I've had to write over the years.
It gets even better if the API itself is backed by some RPC framework. With that, users can simply generate a client and get going.
It feels like we can do better as an industry, this cracked me up because it's so true.
"a single JSON example as the only documentation is... unfortunate"
As someone who’s done lots of RESTful (or RESTish) json/HTTP APIs, lots of gRPC, and lots of GraphQL … the simplest, best solution in almost all cases is RESTful json/HTTP APIs. There’s really no need for gRPC for the rest of us, it’s just unnecessary complexity.
If you want code gen, just edit OAS specs with Stoplight’s OpenAPI editor, and generate clients/servers with OpenAPI generator. If you really need event streaming between services, just use something like Google PubSub, webhooks, Kafka, whatever - external systems are better for this than direct server to server comms because they’re more reliable, far less worries about deployment, etc.
RPC seems simple at first but always balloons into excess complexity. Just stick with REST, and sprinkle in a PubSub system if absolutely necessary, it’ll stay simpler that way.
Put out an example of using it to switch the transport so that it is over NATS instead, this works now thanks to the interop with net/http package: https://github.com/wallyqs/connect-go/commit/2e744ec4bf7ce31...
Internally requests are treated as NATS requests so you would get similar performance and latency as when using core NATS request/response.
There's definitely a tipping point where having language independent interfaces/protobufs and definitions of services are basically mandatory for any cross-team collaboration or work to be possible. But yeah for small teams or single products it really might not be necessary or be total overkill early on in a new product.
Just mindblowing that companies don't adopt a schema-first approach to appeal to a broader customer base. I've lost count of the number of hnd rolled clients I've had to write over the years.
It gets even better if the API itself is backed by some RPC framework. With that, users can simply generate a client and get going.
It feels like we can do better as an industry, this cracked me up because it's so true.
"a single JSON example as the only documentation is... unfortunate"