API Design and Documentation - Poll
Hi everyone,
We're looking for your feedback on our API design and documentation.
Currently, most of our APIs are available as REST and gRPC APIs, but the documentation is only provided as OpenAPI documentation. This can lead to confusion for our customers because not everything can be documented correctly, and we have some missing or wrong documentation because of some limitations on how REST is generated from the gRPC APIs.
We're considering switching fully to gRPC with connect RPC from API version 2 and removing the OpenAPI implementation. For the API/Client we would use buf registry (we already rely on buf to generate the stubs). Some APIs like OIDC, SAML and SCIM are excluded from this. ConnectRpc allows you to still query the apis with a simple curl command and we can easily show examples in our guides. This would allow us to provide more accurate and complete documentation.
Having reached a good level of maturity since joining CNCF in June 2024, connect RPC is now a robust solution, making this the ideal time to adopt it.
Connect RPC curl example:
curl \
--header 'Content-Type: application/json' \
--data '{"sentence": "I feel happy."}' \
https://demo.connectrpc.com/connectrpc.eliza.v1.ElizaService/Say
We'd like to know your thoughts on this. Please take a moment to answer the poll below, and describe the reason for your answer in the chat below.
Thanks for your feedback!21 Replies
Unknown User•8mo ago
Message Not Public
Sign In & Join Server To View
Which API have you currently implemented? Is it the API version 1? We would only remove it from version 2 ongoing. Which means when you migrate from one to the other API, where you anyway need to touch the code, you could directly switch to gRPC. Also with the buf registry this should actually be pretty easy to do so.
I prefer REST over gRPC but that's just a personal preference.
Thanks for the reason. Do I understand it correct if we would get rid of REST, that would be ok for you? Just out of curiosity, whats the reason you prefer REST?
I think in many cases, accessibility and user-friendliness are more important than ‘speed’.
With an identity management system, we are not talking about data-intensive services, nor are we talking about high-performance systems such as real-time stock market calculations or self-driving car calculations.
Instead in many cases we're talking about WAN, manual user interactions and integrations written in JavaScript. So you can hardly benefit from speed (on the wire) anyway.
There are some more pros and cons to REST or gRPC, but it usually boils down to those two.
Do I understand it correct if we would get rid of REST, that would be ok for you?Yes, of course it would be fine with me, even though I'm not a big fan of gRPC. 😄
@flo As you voted for Other, I would be interested in your opinion. What do you mean with other?
Unknown User•8mo ago
Message Not Public
Sign In & Join Server To View
Hey all, thanks for this great feedback so far.
Out of curiosity, do you like REST because you can curl it, or because of the design pattern?
Unknown User•8mo ago
Message Not Public
Sign In & Join Server To View
I don't think GraphQL is well suited for publicly accessible APIs.
For internal communication on distributed systems, it might be a good solution. Maybe for some distinct use cases GraphQL could be used on public facing APIs, but there really aren't many such cases.
Please keep in mind it's not just about what's your favorite buzzword of the day but also about what's a solid foundation for Zitadel. There aren't thousands of dependent objects flying around between dozens of services. In fact there are very little cases you'd really need to query data in any fine-graded by very flexible way.
The rest - excuse me - is spurious arguments.
GraphQL offers a rich type system, which is an advantage vs. REST. Plenty of excellent GraphQL client implementations exist for all major tech-stacks. Good and type-safe clients can be generated from the schema, which serves as a good documentation of the API.All of this is possible for REST APIs too. Good frameworks allow you to generate a proper OpenAPI specification for your API just from the code and as you implement it. It provides type-safety and using an openapi-generator the specification allows you to generate client as well as server (stubs) side code just from the specification. And also please keep in mind: While you can make use of tooling to auto generate code for your API and what not, you can implement a REST API with basically no tooling and almost no knowledge at all at the same time. And that is, what I meant by user-friendliness. Which in my opinion is key to grow your user base.
When discussing this internally we thought that connectRPC brings a good balance for using curl but also having proper contracts.
https://connectrpc.com/
The reason to debate to remove the classic OpenAPI rest from the >=v2 apis is around some challenges we have maintaing gRPC and OpenAPI at the moment. (For example oneOf is broken on the current transformers)
Often when I tinker around new tools I use curl until I am satisfied and then I move to the SDKs (which we can easy auto generate... I.e. https://buf.build/zitadel/zitadel/sdks/main:protobuf (this is a preview and not up-to-date)
GraphQL i find nice for data intesive case, but transactional things I am not such a fan (this is my personal opinion though) 😄
I remember I experienced some limitations with some sort of mutable endpoints some years ago. But it's quite some years ago and I haven't seen that since. The solution usually was having multiple distinct endpoints instead of one.
However, I'm not really familiar with the Go ecosystem. So I can't say anything about the frameworks and tools used there. All I know is that Zitadel is a great application written in Go. 🤣
Thank you 😊
Unknown User•8mo ago
Message Not Public
Sign In & Join Server To View
Well there is some truth in that 😄
But would connectRPC not allow this? One could easy use fetch() to impelement a call without any client stub.
Unknown User•8mo ago
Message Not Public
Sign In & Join Server To View
Got it, I mean our idea is anyway not to tuch the v1 apis with this. Its more forward looking
Unknown User•7mo ago
Message Not Public
Sign In & Join Server To View
Regarding the question of auto-generating clients. As someone who has tried to deal with auto-generated API clients over the years, I've dreaded it every time and the code is usually a pain to deal with.I personally can only speak for openapi-generator which works fine. Of course it needs properly designed APIs, so you definitely have to have some experience in properly designing your API in the first place. Also you might need tweak the generator to have best results. But with that done the results are usually pretty well.
For example. Strava used Swagger so they could auto-generate clients for the Strava API... but they never setup automatically publishing of a JavaScript client to NPM.I wouldn't recommend publishing the generated API clients. You could of course do that, but that's usually not required and might lead to unnecessary confusion and extra work (versioning, updating, ..). Instead make sure your application is able to generate and publish their very own API specification. So users always have the matching specification to the application version they use. Also some modern frameworks are able to do that without much extra work. For example see FastAPI: https://fastapi.tiangolo.com/tutorial/metadata/#openapi-url
Thanks for all your feedback