Document which endpoints have efficient etags (and documentation for integration developers on how to use caching)

[brontolosone]

Document which endpoints have efficient etags (and documentation for integration developers on how to use caching)

• General section on how to use it
• Per-endpoint short mention with link to the general section

[brontolosone]

The best practice guide, plus announcement in the API doc release notes, might suffice.

The other part is tagging endpoints of api.yaml with information on whether there are etags and if so whether they're of the newfangled kind? I think that the latter could be considered an implementation detail, and the former is evident from looking at a response, or do we think the same people who would know how to implement caching wouldn't know how to look for whether a response contains an ETag?
Plus I'm tempted to remove some superfluous etags in the future, as the Express out-of-the-box etagging is also applied to 4xx/5xx responses, which interferes with potential caching at the reverse proxy level. The blanket caching doesn't make sense everywhere anyway. I do think adding some sort of "Cacheable" lozenge for every endpoint where it makes sense could be good for uptake, because yes we would like integration writers to get good performance and not melt their servers.
Thus I propose to postpone adding those "Cacheable!" lozenges (of some sort) until we've got our story straight, for instance with regard to these complications.

[lognaturel]

Sounds good!