ETags

[benbunk]

Add support for the HTTP Protocol's ETags which enable end users to cache anonymous requests and thus reduce origin load and increase client responsiveness.

Documentation on the RFC can be found here: http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.19

An implementation of ETags can be found in the GDATA API v2.0: https://developers.google.com/gdata/docs/2.0/reference#ResourceVersioning

Google is shifting their API resources around so there's a deprecated warning on this page but the section on ETags is current:

[bryanhirsch]

Thanks for this suggestion @benbunk.

Do you think this should be a requirement across all White House APIs? Or an optional recommendation?

As this document grows, we'll probably separate standards/requirements and recommendations.

[benbunk]

I guess it could go either way. I'm a bit more in favor of standardizing it. It would seem a bit odd to have ETags on one resource and not another because I would assume META about a request would be fairly standardized across the API. Even if ETags are left out entirely it might be worth adding a verison id to the resources.

It is worth noting that the ETag would need to change with each modification to the resource. So for instance in Drupal the currently published VID (version id) would make a good ETag. In other systems I'm not sure how this would be generated.

There is also a server side component to this that when the ETags on the local resource and in the HTTP request match than the server responds with a 304 Not Modified. Which would also require adding an additional HTTP Code to the API docs that I left out in this pull request.

[lheyman]

Closing this. @benbunk I agree (we all do) that it would be bad/odd to have ETags on some resrouces but not others, but we're also not yet prepared to require them as part of this standard.

[inadarei]

Can somebody please provide justification on: why ETags on some resources is worse than no Etags at all? Are you saying some caching is worse than no caching? IMHO, that sounds like a very non- "web-y" approach. All of web's architectural scalability is based on the attitude of "do as much of the right thing as you can". The Must Ignore principle being a good example.

@benbunk, VID may not be the best choice for ETag even in Drupal. It's important to remember that API responses are the "representations" of a resource, not the resource itself. It is quite reasonable to assume that a representation may be customized for an individual API client (permissions? content rights?). In such cases while VID is the unique id for the resource, it is not such thing for the API clients.