Review HTTP API responses

[mrekucci]

Focus on setting standards for HTTP API endpoints so that the way they respond is consistent across all endpoints and so that consumers of our API are surprised as little as possible. Specifically:

• check if the response messages are meaningful to API consumers
• check if the log messages are consistent with the response messages
• check that response messages and log messages are consistent across all endpoints (maintain the same style)
• check that response messages do not leak unnecessary information, e.g.: errors, etc...
• consider using the logger WithName(...) build method to identify handlers
• document the style chosen for log messages and responses

Also schedule a meeting with the JS team to get their feedback on the usability and ergonomics of our HTTP API, as they are big users of it. Process the feedback and engage with it.

Resources:

• https://cloud.google.com/apis/docs/http
• https://cloud.google.com/apis/design/errors
• https://cloud.google.com/blog/products/api-management/restful-api-design-what-about-errors
• https://cloud.google.com/apigee/resources/ebook/web-api-design-register/index.html