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!9 Replies
Unknown User•4mo 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.
Unknown User•4mo ago
Message Not Public
Sign In & Join Server To View
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?
Unknown User•4mo ago
Message Not Public
Sign In & Join Server To View
@flo As you voted for Other, I would be interested in your opinion. What do you mean with other?
Unknown User•4mo ago
Message Not Public
Sign In & Join Server To View
Thanks for all your feedback