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:
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!
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
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!
