140 lines
8.6 KiB
XML
140 lines
8.6 KiB
XML
<xml>
|
|
<brief>Get the list of changes for your database</brief>
|
|
<issue-id>109</issue-id>
|
|
<desc>
|
|
<p>Get the list of changes to be <u>replayed on your own copy
|
|
of Opencaching database</u>. Use this method periodically (e.g. every 5 minutes) to
|
|
keep your database in sync with ours.</p>
|
|
|
|
<p>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 <b>replicate</b> module to achive this effect. The <b>changelog</b> 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 <b>fulldump</b> method.</p>
|
|
|
|
<p>A couple of things for you to remember:</p>
|
|
<ul>
|
|
<li>You <b>must</b> update your database frequently for this method to work.
|
|
We don't keep the changelog indefinitelly. You must update at least once a week!</li>
|
|
|
|
<li>You <b>should not</b> 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.</li>
|
|
</ul>
|
|
|
|
<p>Let's assume that you already have a copy of OKAPI database, but it's
|
|
already 2 days old. You want to use the <b>changelog</b> method to update
|
|
your copy to the most current state.</p>
|
|
|
|
<p>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.</p>
|
|
|
|
<p>We use <b>revision</b> numbers to keep track of all the versions of the
|
|
database. Every time we update a database, the <b>revision</b> 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!</p>
|
|
|
|
<p><b>Example.</b> This is a valid list of requests you should issue and their
|
|
responses:</p>
|
|
|
|
<ul>
|
|
<li><b>fulldump</b> - you receive a fulldump of our database with the
|
|
revision number 238004. <b>You will call this method only once</b> (to
|
|
initiate your copy of the database).</li>
|
|
|
|
<li><b>changelog</b>?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.</li>
|
|
|
|
<li>You wait for some time between requesting the changelog again.</li>
|
|
|
|
<li>Upon your next update, you'll ask for <b>changelog</b>?since=238017, etc.</li>
|
|
</ul>
|
|
</desc>
|
|
<req name='since'>
|
|
<p>Current revision of your database. This should be the same as the value
|
|
of <b>revision</b> attribute, which you received with your previous update.</p>
|
|
|
|
<p>Old revisions are deleted, the <b>since</b> 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!).</p>
|
|
</req>
|
|
<common-format-params/>
|
|
<returns>
|
|
<p>A dictionary of the following structure:</p>
|
|
<ul>
|
|
<li>
|
|
<p><b>changelog</b> - a <b>list</b> of dictionaries. Each dictionary has the following structure:</p>
|
|
<ul>
|
|
<li>
|
|
<p><b>object_type</b> - string, object type to which the change refers to. One of the following values:</p>
|
|
<ul>
|
|
<li><b>geocache</b> - this change refers to a geocache object,</li>
|
|
<li><b>log_entry</b> - this change refers to a log entry.</li>
|
|
</ul>
|
|
<p>More object types will come in the future. You should ignore all changelog
|
|
entries with an unknown object_type.</p>
|
|
</li>
|
|
<li>
|
|
<p><b>object_key</b> - a dictionary of fields which compose the primary key for the object.
|
|
This will be the <b>code</b> field for the <b>geocache</b> object, and <b>uuid</b> field
|
|
for the <b>log_entry</b> object.</p>
|
|
</li>
|
|
<li>
|
|
<p><b>change_type</b> - string, the type of the change. One of the following values:</p>
|
|
<ul>
|
|
<li><b>replace</b> - 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.</li>
|
|
<li><b>delete</b> - the object was deleted. You should check if you already have
|
|
the object in your database. If you do, you should delete it.</li>
|
|
</ul>
|
|
</li>
|
|
<li>
|
|
<p><b>data</b> - a dictionary of fields associated with the object (present only
|
|
if <b>change_type</b> equals <b>replace</b>).</p>
|
|
<ul>
|
|
<li>For <b>geocache</b> 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).</li>
|
|
<li>For <b>log_entry</b> objects, this might be any subset of fields described
|
|
in the services/logs/logs method, <b>plus</b> additional <b>cache_code</b> field,
|
|
the code of the geocache to which the log entry refers to.</li>
|
|
</ul>
|
|
<p>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.</p>
|
|
</li>
|
|
</ul>
|
|
<p>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 <b>since</b> parameter and it MAY contain some more, which were submitted
|
|
<b>before</b> 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).</p>
|
|
</li>
|
|
<li>
|
|
<p><b>revision</b> - this is the revision number which you should use in the <b>since</b> parameter
|
|
when you call this method next time.</p>
|
|
</li>
|
|
<li>
|
|
<p><b>more</b> - boolean. If <b>false</b>, then it means that the entire changelog had been
|
|
pulled. If <b>true</b>, then there are more items waiting to be pulled - you should rerun this
|
|
method again (with the value of <b>revision</b> inserted in the <b>since</b> parameter).</p>
|
|
<p>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 <b>more</b> attribute. It makes it
|
|
easier to parse the changelog sequentially.</p>
|
|
</li>
|
|
</ul>
|
|
<p>The response MAY contain changes recorded before the revision which you stated in your <b>since</b>
|
|
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 <b>revision</b> and <b>more</b> attributes in a correct way, which
|
|
in turn will make you query us again, if you need to.</p>
|
|
</returns>
|
|
</xml> |