summaryrefslogtreecommitdiff
path: root/data/docs
diff options
context:
space:
mode:
authorYorhel <git@yorhel.nl>2009-11-14 12:57:14 +0100
committerYorhel <git@yorhel.nl>2009-11-14 12:57:14 +0100
commitc7ff7086534cd9de7ce4043eb10c7161401c1b96 (patch)
tree983e757eded42ba65d092f1eccc69fb5725bc28e /data/docs
parent848cae8e13d6ab8110caff39acf671822659de08 (diff)
d11: Finalized API documentation
Diffstat (limited to 'data/docs')
-rw-r--r--data/docs/1147
1 files changed, 36 insertions, 11 deletions
diff --git a/data/docs/11 b/data/docs/11
index f1c84dce..199935fd 100644
--- a/data/docs/11
+++ b/data/docs/11
@@ -1,10 +1,4 @@
:TITLE:Public Database API
-
-<div class="warning">
- <h2>IN DEVELOPMENT</h2>
- <p>This API is currently in development, pretty much everything is subject to change without notice.</p>
-</div>
-
:INC:index
:SUB:Introduction
@@ -64,10 +58,10 @@ server resources and prevent abuse of this service.</p>
</ul>
<br />
-<b>Test version:</b>
+<b>Connection info:</b>
<dl>
- <dt>Host (beta)</dt><dd>beta.vndb.org</dd>
- <dt>Port</dt><dd>19534 ('VN')</dd>
+ <dt>Host</dt><dd>api.vndb.org (primary), beta.vndb.org (available for testing)</dd>
+ <dt>Port (tcp)</dt><dd>19534 ('VN')</dd>
</dl>
<br />
@@ -98,6 +92,35 @@ server resources and prevent abuse of this service.</p>
</li>
</ul>
+<br />
+<b>Implementation tips</b>
+<p>Like the disclaimer, these notes should be obvious, but it can't hurt to state them anyway.</p>
+<ul>
+ <li>
+ <b>Cache</b> everything you receive, the data on VNDB doesn't change very
+ often. Even if you only refresh the cached information once every month, you
+ can be sure that most of the data hasn't changed within that time.
+ </li>
+ <li>
+ Program defensively. Even when the documentation says that a string will be
+ returned, it may very well happen that this is later changed into an array.
+ Make sure your application doesn't completely crash in such an event. Also keep
+ in mind that for every command you send, the server can reply with an error, or
+ can immediately close the connection (but this is be rare).
+ </li>
+ <li>
+ Regularly check this page to see if anything has changed to the API, and
+ update your client where necessary. I'll probably add a changelog to the bottom
+ of this page to make this easier.
+ </li>
+ <li>
+ Use a JSON library for both encoding and decoding JSON data. While the format
+ is relatively easy to use, you're much more likely to introduce bugs when you're
+ writing your own parser.
+ </li>
+</ul>
+
+
:SUB:Request/response syntax
<p>
@@ -426,8 +449,9 @@ however still required.<br />
<td>= !=<br />= != &gt; &gt;= &lt; &lt;=</td>
<td>
Note that matching on partial dates (released = "2009") doesn't do what
- you want, use ranges instead, e.g. (released > "2008" and released <= "2009").
+ you want, use ranges instead, e.g. (released &gt; "2008" and released &lt;= "2009").
</td>
+ </tr>
<tr class="odd">
<td>platforms</td>
<td>null<br />string<br />array of strings</td>
@@ -449,6 +473,7 @@ however still required.<br />
novel and its releases. Note that the algorithm of this search may change and
that it can use a different algorithm than the search function on the website.
</td>
+ </tr>
</table>
:SUBSUB:get release
@@ -851,7 +876,7 @@ however still required.<br />
<dt>missing</dt><dd>A JSON object argument is missing a required member. The name of which is given in the additional "field" member.</dd>
<dt>badarg</dt><dd>A JSON value is of the wrong type or in the wrong format. The name of the incorrect field is given in a "field" member.</dd>
<dt>needlogin</dt><dd>Need to be logged in to issue this command.</dd>
- <dt>throttled</td><dd>
+ <dt>throttled</dt><dd>
You have used too many server resources within a short time, and need to wait
a bit before sending the next command. The type of throttle is given in the
"type" member, and the "minwait" and "fullwait" members tell you how long you