Caching

The FamilySearch API is designed to adhere to RESTful principles, especially that of caching. Caching influences much of the design of the API.

Why Caching?

The goal of caching is to increase performance. This is done in several ways:

  • Client caching can prevent the need for some network requests.
  • Reverse cache proxies can respond to requests without the origin servers and databases needing to respond.
  • Servers can be allowed to tell clients that their cache is still valid, decreasing the number of network requests.

The central point is to enable more work to be done without having to make a costly request to the server. The more requests that the reverse cache proxies can respond to, the faster the application runs and the more it can scale. Everyone benefits from caching.

ETags

An ETag is an opaque identifier assigned by a web server to a specific version of a resource found at a URL. If the resource content at that URL ever changes, a new and different ETag is assigned. Used in this manner ETags are similar to fingerprints, and they can be quickly compared to determine if two versions of a resource are the same or not. Comparing ETags only makes sense with respect to one URL; ETags for resources obtained from different URLs may or may not be equal, so no meaning can be inferred from their comparison.

Wikipedia

The FamilySearch API provides ETags on Persons, Relationships, Change History, Discussions, and Sources. The ETags are weak, meaning that resources with matching ETags are semantically equivalent, but not byte-for-byte identical. In other words, the data is the same but might be in a different order.

While ETags are a replacement for version numbers, they are not sequential. That is, a comparison can determine only whether two resources are the same; a comparison cannot determine which revision is most recent.

To check the current version of a resource without being sent the actual resource in the response, you can do a HEAD request and check the ETag that is returned. HEAD requests return the same headers that would be returned in a GET request.

Request 
HEAD /platform/tree/persons/KWQY-DCB

Response
HTTP/1.1 200 OK
Last-Modified: Thu, 24 Jan 2013 21:59:56 GMT
ETag: W/"a7bd095f6058737fc90e709453352acc74903a0b"
Content-Type: application/xml
Cache-Control: no-transform, max-age=3600
Content-Location: /platform/tree/persons/KWQY-DCB

You can also perform a conditional GET by specifying the If-None-Match header. A conditional GET means the resource is returned only if the ETag in the If-None-Match header does not match the current version. When the specified ETag does match the current version, a 304 Not Modified is returned.

Request 
GET /platform/tree/persons/KWQY-DCB
If-None-Match: W/"a7bd095f6058737fc90e709453352acc74903a0b"

Response
HTTP/1.1 304 Not Modified
Last-Modified: Thu, 24 Jan 2013 21:59:56 GMT
ETag: W/"a7bd095f6058737fc90e709453352acc74903a0b"
Content-Type: application/xml
Cache-Control: no-transform, max-age=3600
Content-Location: /platform/tree/persons/KWQY-DCB

Conditional GETs prevent the need to perform a HEAD request to check for a new version and then performing a GET request to get the new version when available.

No Batch Endpoints

Caching is the reason the FamilySearch API does not offer a batch person endpoint. Requests to batch endpoints are not cacheable. Because URIs are used as the key, responses to persons?id=1,2,3 and persons?id=3,2,1 are stored separately even though they are semantically equivalent. By allowing for persons to be requested only one at a time, we maximize the cache efficiency, which in turn decreases the load on our servers and allows the system to run faster.

Authorization Header

Caching is also the reason we recommend using the Authorization header to authenticate requests. If you use the access_token query parameter, then resources can be cached only for that session (since the cache is keyed by the URL). This is why the following warning header is applied to the response when you use the access_token query parameter:

Warning: 199 FamilySearch Best Practice Violation: Authorization header should be used instead of using the access_token query parameter.