Document expected status codes in API documentation #17
Description
The Server and Agent APIs currently provide only a short description of the purpose of each RPC with documentation of each request/response field. It would be helpful to API clients to also be able to see all the expected gRPC status codes for each RPC, with a description of the cases in which each status code is returned. Clients need to understand why a particular status code would be returned so they can determine how to handle it. API dashboards and alerting also need to be built around these status codes.
Documenting the expected RPC status codes in the protobuf presents the following advantages:
- One place for all information you need as a consumer of SPIRE APIs. Right now, to discover the returned status codes requires studying the implementation of the APIs. This is not always easy to do because it requires examining middleware and API handler code.
- Establishes expected status codes explicitly as part of the API contract. This will help catch potential API regressions that may break client consumption/alerting.