This section describes how EDAA uses http headers, specifically eTags, and the Accept header for API version and language negotiation.
Language Negotiation
A consumer of an EDAA may use the http Accept-Language header to specify which languages/locales it would prefer certain human-readable components of the response be translated into. Currently, EDAA defines the Message information item of an Error resource as the only normative aspect that is governed by the Accept-Language header. An EDAA MAY use language preference to alter other aspects of the response formatting.
Note also that EDAA supports an alternative form of expressing language preference. An language= optional query parameter may also be included on EDAA URIs to specify consumer preference for language/locale. If the client request uses both the Accept- Language header and an language= query parameter to express preference for the response format, then a response is given only if there is at least one language/locale that overlaps between the Accept-Language header and the languages= header. For example a request:
GET /types?language=da Accept-Language: es, en-gb;q=0.8, en;q=0.7contains a conflict between the language query parameter and the Accept-Language: header. There is no language/locale that matches both criteria. In this case, the server must return an error (406 not acceptable).
JSON Equivalent of Feed and Entry eTags
EDAA implementations are encouraged to support the notion of eTags for cache control and optimistic concurrency control.
EDAA implementations that implement eTags and also support the JSON serialization format described in this page MUST annotate those feeds and entries with eTags. Feed level eTags should be weak eTags and entry level etags should be strong eTags.
Here is an example of an eTag at the feed level:
{
"etag": 'W/"C0QBRXcycSp7ImA9WxRVFUk."'
... other metadata about the feed
"entries":[
{
entry ...
},
... etc for all the entries in the feed
],
...
}
Here is an example of an eTag at the entry level:
{
"etag": '“ADEEFO42drp7tKA7QxRDBIL."'
other metadata about the entry... ,
representation of a resource within the content object ... ,
...
}, ...
}
Using eTag in a GET
For this, we assume the EDAA is supporting eTags in the style described by EDAA. The consumer could issue a GET operation, for example:
GET /types/FileServer/instancesand the response might look like:
<?xml version="1.0" encoding="UTF-8"?> <atom:feed ... xmlns:gd='http://schemas.google.com/g/2005' gd:etag='W/"B9roqXcycSp7ImA9WxRVDdk."'> ... <atom:link href="https://.../types/FileServer/instances" rel="self”/> ... <atom:entry ... xmlns:gd='http://schemas.google.com/g/2005' gd:etag='“U822F2drp7tKA7QxRD2Ko."'> ... <atom:link rel='self' href='http:.../instances/Fileserver::1234' /> ... </atom:entry> <atom:entry> ... </atom:feed>
At some point later in time, the consumer may want to "refresh" the feed to see if anything had changed. Clearly the consumer could re-issue the same GET and reprocess the response. However, if the consumer has a cached copy of the feed it previously retrieved and if it re-issued the operation as follows:
GET /types/FileServer/instances If-None-Match: W/"B9roqXcycSp7ImA9WxRVDdk."Then the EDAA could note that the eTag in the If-None-Match header matches the eTag associated with its version of the feed, and if they match, return an http 304 (not modified) status code with an empty response body. Saving processing time on the server side, saving network bandwidth, reducing the latency of the response to the client and saving the client from having to re-process a feed that is no different from the version it already has. Of course, if the eTags don't match then a full response is returned to the consumer with http 200 (ok) status code.
This also works at the entry level. The consumer could inspect entry level eTags, and using the @href in the rel="self" atom:link within the atom:entry, could issue a request to "refresh" the value of the entry if that entry had changed:
GET /instances/Fileserver::1234 If-None-Match: “U822F2drp7tKA7QxRD2Ko."And the EDAA could check if the eTags match, and if they do, return the 304 response, but if they don't, send a full response with 200 (ok) status.
Using eTag in a PUT or PATCH operation
For this, we assume the EDAA is supporting eTags in the style described by this spec. The consumer could issue a GET operation, for example:
GET /types/FileServer/instances and the response might look like: <?xml version="1.0" encoding="UTF-8"?> <atom:feed ... xmlns:gd='http://schemas.google.com/g/2005' gd:etag='W/"B9roqXcycSp7ImA9WxRVDdk."'> ... <atom:link href="https://.../types/FileServer/instances" rel="self”/> ... <atom:entry ... xmlns:gd='http://schemas.google.com/g/2005' gd:etag='“U822F2drp7tKA7QxRD2Ko."'> ... <atom:link rel='self' href='http:.../instances/Fileserver::1234' /> ... </atom:entry> <atom:entry> ... </atom:feed>At some point in the future, the consumer may wish to use PUT or PATCH to make modifications to the resource. When an EDAA decorates response feeds with eTag elements, then it MUST also require consumers to annotate any resource modification request with an http If-Match header containing the eTag of the resource being modified. For example, to modify the FileServer instance retrieved in the previous example, a PUT request as follows could be formed:
PUT /instances/Fileserver::1234 If-Match: “U822F2drp7tKA7QxRD2Ko." ... body of the PUT contains a partial representation (for update) of a FileServer instanceNote, the content of the If-Match: header is the eTag value contained in the atom:entry corresponding to the resource being updated. The EDAA MUST compare the value of the eTag given in the If-Match header with the current eTag value for the resource. If the values match, the modification operation may proceed. If the values do not match, the EDAA MUST respond with an http 412 (Precondition Failed) response.
If the EDAA provided an eTag with the resource representation, as shown above, and the consumer does not include an If-Match: header in a modification request, then the EDAA MUST reject the request with an http 412 (Precondition Failed) response.
