Get the list of changes for your database

:: services/replicate/changelog method

Get the list of changes to be replayed on your own copy
of Opencaching database. Use this method periodically (e.g. every 5 minutes) to
keep your database in sync with ours.

For some applications it might be desireable to have a quick access to the entire
Opencaching database (instead of querying for specific portions of it). You may use
OKAPI's replicate module to achive this effect. The changelog method
is the primary replication service which you will use. However, to correctly set up
your first database copy, you will need to use the fulldump method.

A couple of things for you to remember:

You must update your database frequently for this method to work.
We don't keep the changelog indefinitelly. You must update at least once a week!

You should not update your database more frequently than once per
5 minutes. This could kill our servers, and it wouldn't do you any good, since
we update the changelog only once every 5 minutes anyway.

Let's assume that you already have a copy of OKAPI database, but it's
already 2 days old. You want to use the changelog method to update
your copy to the most current state.

Changelog is the list of all changes which appeared in the OKAPI database
since the last time you downloaded it. What you have to do is to download this
list of changes and to replay them on your copy of our database. After you do
this, your database is up-to-date.

We use revision numbers to keep track of all the versions of the
database. Every time we update a database, the revision is increased.
You will also receive this number every time you fetch a changelog or a fulldump
of our database. You must keep this number carefully, because you need
it in order for us to generate a proper changelog for you next time you ask
for it!

Example. This is a valid list of requests you should issue and their
responses:

fulldump - you receive a fulldump of our database with the
revision number 238004. You will call this method only once (to
initiate your copy of the database).

changelog?since=238004 - OKAPI checks if there were any changes
recorded since revision 238004. It responds with the list of changes and the
new revision number 238017. You replay the changes on your database.

You wait for some time between requesting the changelog again.

Upon your next update, you'll ask for changelog?since=238017, etc.

since

required

Current revision of your database. This should be the same as the value
of revision attribute, which you received with your previous update.

Old revisions are deleted, the since argument MUST referer to a revision no older
than 10 days. You will have to download a fulldump if you have an older copy
(shame on you!).

changelog - a list of dictionaries. Each dictionary has the following structure:

object_type - string, object type to which the change refers to. One of the following values:

geocache - this change refers to a geocache object,

log_entry - this change refers to a log entry.

More object types will come in the future. You should ignore all changelog
entries with an unknown object_type.

object_key - a dictionary of fields which compose the primary key for the object.
This will be the code field for the geocache object, and uuid field
for the log_entry object.

change_type - string, the type of the change. One of the following values:

replace - the object was inserted or updated. You should check if you
already have the object in your database. If you have it, you should update its
fields accordingly. If you don't, you should create it.

delete - the object was deleted. You should check if you already have
the object in your database. If you do, you should delete it.

data - a dictionary of fields associated with the object (present only
if change_type equals replace).

For geocache objects, this might be any subset of fields described
in the services/caches/geocache method. Note that not all of these fields will
be included here (i.e. latest_logs will not).

For log_entry objects, this might be any subset of fields described
in the services/logs/logs method, plus additional cache_code field,
the code of the geocache to which the log entry refers to.

In theory this dictionary should contain only these fields which actually changed.
In truth, it MAY contain all the other fields too. This behavior may change in future.

You should iterate through this changelog sequentially. All the changes should be applied
in the same order as they were listed in the changelog. Single object may appear multiple times
inside the changelog. Changelog will contain all the changes which occured since the time you
specified in the since parameter and it MAY contain some more, which were submitted
before this date (see below). The changes which are unnecessary MAY be skipped (ex. when
cache description changes multiple times, we may want to include only the last change).

revision - this is the revision number which you should use in the since parameter
when you call this method next time.

more - boolean. If false, then it means that the entire changelog had been
pulled. If true, then there are more items waiting to be pulled - you should rerun this
method again (with the value of revision inserted in the since parameter).

The changelog is usually tiny, but it also might be huge at times. It may even
contain all the caches in the database (i.e. if we decide to do some changes on all
caches in a bulk). This is the reason why we introduced the more attribute. It makes it
easier to parse the changelog sequentially.

The response MAY contain changes recorded before the revision which you stated in your since
parameter. This is due to caching. If we already have a response ready, that was produced for a
"since" parameter which was a little more in the past, we may want to return this cached copy,
instead of producing a new one. It will be faster for us, and you shouldn't even notice. We will
still make sure to set the revision and more attributes in a correct way, which
in turn will make you query us again, if you need to.