API for accessing ETag values

[alexanderwhatley]

As discussed in #54, I think it would be a good idea of exposing API functions that can explicitly access the value of the ETag of the firebase db.

We could have the following API for the Reference class:

get(self, etag=False) # When etag is True, behaves like _get_with_etag()
set(self, value, etag=None) # When etag is not None, behaves like _update_with_etag()
get_etag(self) # Retrieves the etag without the corresponding data
check_etag(self, etag) # Returns a boolean indicating whether or not the etag is correct

These API functions could come in handy for low level operations that the user may want to perform that the proposed transaction functionality may not be able to handle. An example would be if the user keeps a cache of some of the firebase data, the user will likely want to keep track of the ETag for each part of the database, so he can check whether the data in some part of the cache is up to date.

[alexanderwhatley]

@caseycrogers, you said in the comments for #54 that

As for your interest in adding low-level access to ETags-this seems reasonable to me. However, there is a caveat:

As-is, the ETag of a given value at one path in the database will be the same as the ETag of the same value at any other path.

Additionally, the ETag of values will not change with time. However, we do not document these two properties and do not guarantee that EITHER of them will remain true in the future. As such, we strongly discourage developers from fetching ETag values and then saving them to be used with later transactions at the same or different locations.

I don't think that this is a problem in the case of caching. If the data is the same, and hence the ETag is the same, then the cache is not stale. Also, it does not matter here if the ETag does not change as a function of time (I would certainly think that we would not want it to!)

[caseycrogers]

By change as a function time I mean that in the future we may choose to change our algorithm for producing ETags. We have no such plans at the moment but want to keep the option open for ourselves.

For caching it should be fine. Another note that you might find very helpful-while implementing the conditional requests logic I also implemented full support for the if-none-match header. However, since this feature was well out of scope of the project (allowing transactions in REST) we decided to keep the functionality but not document it. If you're doing any caching related stuff I highly recommend you use if-none-match.

It may be even worthwhile to add under-the-hood caching functionality with if-none-match to this library's default GET implementation. Preferably with a flag to turn it on or off.

Requests for non-stale data in the cache would incur one round trip (to verify the cached value) and minimal bandwidth. Stale data would require two round trips and slightly higher bandwidth than just a single standard GET.

[alexanderwhatley]

Just submitted a pull request for this. I think I'll hold off on the under-the-hood caching for now, as that seems like it'll be pretty complicated.

[hiranya911]

I will resolve this, since get(etag=True) and set_if_unchanged() are already implemented and released. I also just sent out #73 to add the get_if_changed() method. Thanks @alexanderwhatley for all your hard work on getting this implemented, and thanks @caseycrogers for all the help.