<xml>
	<brief>Download OKAPI database snapshot</brief>
	<issue-id>110</issue-id>
	<desc>
		<p><b>Beta status.</b> Download the latest snapshot of OKAPI database. You should call this method
		only once in your lifetime.</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><b>Important:</b> This method MAY change substantially or it might even get removed.
		We don't plan on doing this, but we may be forced to (i.e. to prevent abuse).</p>
		
		<p>A couple of things for you to remember:</p>
		
		<ul>
			<li>Currently, this functionality is available <b>for developers only</b>,
			NOT for the individual users. We don't want users to download a fresh snapshot of
			the entire database every time they want, this could kill our servers.
			If you want to enable such features for your users, you can do it, but you
			must use <b>your own server</b> for data traffic (especially, fulldump requests).</li>
			<li>Fulldump is a copy of the entire database. We generate such copy once every couple of
			days. This copy if intended for you to start only, later you must use the changelog to
			keep it up-to-date.</li>
			<li>Every time our database is extended (new fields or new object types), and you want to
			make use of these new fields, you are of course allowed to download a fulldump copy again.</li>
			<li>There is no XMLMAP version of this file.</li>
		</ul>
	</desc>
	<returns>
		<p>Archive with JSON-encoded files. File named <b>index.json</b> will contain a dictionary
		of the following structure:</p>
		<ul>
			<li><b>revision</b> - revision of the database snapshot contained in the archive,</li>
			<li><b>data_files</b> - list of filenames which contain the changelog entries for
			you to parse. Each file contains a JSON-encoded list of changelog entries, in format
			described in the <b>changelog</b> method ("replace" only).</li>
			<li><b>meta</b> - a dictionary of other meta data, not important.</li>
		</ul>
		<p>Note: We use TGZ or TBZ2 format to encode this archive:</p>
		<ul>
			<li><b>TGZ</b> archive (more commonly known as <b>.tar.gz</b> archive) is a TAR
			archive compressed with GZIP.</li>
			<li><b>TBZ2</b> archive (more commonly known as <b>.tar.bz2</b> archive) is a TAR
			archive compressed with BZIP2.</li>
		</ul>
		<p>There are many tools available for handling these archives. In Linux, try "tar -xf filename".</p>
	</returns>
</xml>