Use Etags to check for custom provider updates

Both social login applications and Custom Providers support ETags and the If-Not-Match header. What does that mean, exactly? Well, if you use the /engage-v2/app/{appId} operation to return information about a social login application, or if you use the /engage-v2/app/{appId}/custom-providers/{providerId} operation to return information about a custom provider, one of the headers associated with the API response is the ETag header:

This header differentiates successive versions of a social login application or custom provider: each time the application or the custom provider is updated, a new ETag is assigned to the item. For example, the custom provider shown above has the ETag value 2e90ad826eb67a3e17cbbd810b3844b2b385008b5d752d4b53c642fefbc69820. After making a change to the provider, the value of the ETag also changes; for example, the new tag might be 3089bb312ab43435d836bffc0ded1ba9a868dbbef8f350ce0a0c8127d7bb47f2. Because the ETags are different, that tells us that an older version of the provider has been superseded by a newer version:

     Original Etag Value: 2e90ad826eb67a3e17cbbd810b3844b2b385008b5d752d4b53c642fefbc69820
    Updated Etag Value: 3089bb312ab43435d836bffc0ded1ba9a868dbbef8f350ce0a0c8127d7bb47f2

In many ways, the Etag is just a lengthy -- and very opaque -- version number.

But here’s the question: do Etags even matter to you? Well, if you’re a web developer, it might. For example, suppose that, sometime in the past, you used the GET method to return information about a custom provider; you then took that information and used it to carry out additional processing of some kind (for our purposes, it doesn’t matter what kind of processing). 

Suppose you’re now tasked with checking to see if that information is still valid; in other words, has the provider been updated since the last time you made an API call against it? One way to do that is to retrieve the latest version of the provider and check the current properties and property values against the old properties and property values. That works, but a faster, more efficient way to do that same thing is to use the ETag header.

Here’s how the Etag process plays out. Suppose the last time you retrieved information for the provider the ETag header was set to 3089bb312ab43435d836bffc0ded1ba9a868dbbef8f350ce0a0c8127d7bb47f2. To see if the provider has been changed since then, add the If-None-Match header to your API call and set the value to the old Etag value. In Curl, that API call might look something like this:

curl -L -X GET \
  'https://v1.api.or-stg.janrain.com/3cc14467-fd4f-437d-a0c0-0b3888dd2ee4/v2/config/low/services/engage-v2/apps/fifbclhccfpjdeoejkag/custom-providers/d284e861-d7f9-426e-93b0-56e01cf6d0ea' \
 -H 'If-None-Match: "3089bb312ab43435d836bffc0ded1ba9a868dbbef8f350ce0a0c8127d7bb47f2"' \
  -H 'Authorization: Bearer 4kcWwH40pIf3v8gWvA-1dEnEWYWcKwMisItN3WOc9VvPaioNilro2lsgiu6fX3L-'

In Postman, that additional header looks like this:

When you make your API call, the value of the If-None-Match header is checked against the ETag value currently assigned to the provider. If the values are different, that means that the provider has changed since the last time you looked at. In that case, you’ll also get back the up-to-date list of properties and property values of the provider.

However, if the two ETag values are identical that means that the provider hasn’t changed since the last time you checked. Because of that, you won’t get back any properties or property values: the assumption is that you already have this information. Instead, you’ll get back the HTTP status code 304 Not Modified, which tells you that the provider ETag matches the If-None-Else Etag.

That work flow looks something like this:

And what if you want to get back the current set of properties and property values, regardless of whether or not those values have changed? That’s fine: in that case, just leave off the If-None-Match header.