ServiceControl APIs are a wild mix and do not follow sane HTTP API guidance

[danielmarbach]

Describe the suggested improvement

ServiceControl has a wild mix of approaches when it comes to HttpAPIs which makes interacting with those APIs vary on a case by case basis. Some things we have observed:

• ServiceControl uses combined ETAGs that are sometimes used and sometimes not. It is unclear how those ETAGs in the current form provide value (if at all)
• ServiceControl used the HTTP ReasonPhrase which is no longer supported in HTTP2.0. To workaround, we had to introduce a dedicated X-PARTICULAR-REASONPHRASE header. Probably using something like problem details eventually would be a saner approach.
• StatusCodes are messy and sometimes make little sense
• There is no API documentation
• Scatter/Gather requires deserialization and re-serialization which makes things horribly inefficient

It would be good to introduce OpenAPI specs and rework the APIs to follow sane HTTP guidelines

Additional Context

No response

[johnsimons]

@danielmarbach regarding the new X header, that convention has been deprecated for a while, https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers

[johnsimons]

Regarding the etags, if memory serves me and things have not changed, those were introduced by a much younger John 😜, the idea was to improve ServiceInsight performance and hence lean on etags to cache responses since those should be immutable.

[johnsimons]

Regarding OpenApi, that is great if the rest api is to be consumed by external customers but if that is not the case, there is a “tax” involved in maintaining it.
If we are to enforce certain guidelines in our rest api for example, all POST requests must return 201, I wonder if Roslyn analysers could help us.