|author||Yorhel <email@example.com>||2009-11-14 12:57:14 +0100|
|committer||Yorhel <firstname.lastname@example.org>||2009-11-14 12:57:14 +0100|
d11: Finalized API documentation
Diffstat (limited to 'data')
1 files changed, 36 insertions, 11 deletions
diff --git a/data/docs/11 b/data/docs/11
index f1c84dce..199935fd 100644
@@ -1,10 +1,4 @@
:TITLE:Public Database API
- <h2>IN DEVELOPMENT</h2>
- <p>This API is currently in development, pretty much everything is subject to change without notice.</p>
@@ -64,10 +58,10 @@ server resources and prevent abuse of this service.</p>
- <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>
@@ -98,6 +92,35 @@ server resources and prevent abuse of this service.</p>
+<p>Like the disclaimer, these notes should be obvious, but it can't hurt to state them anyway.</p>
+ <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.
+ 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).
+ 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.
+ 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.
@@ -426,8 +449,9 @@ however still required.<br />
<td>= !=<br />= != > >= < <=</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 > "2008" and released <= "2009").
<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.
@@ -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>
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