diff options
Diffstat (limited to 'data/docs')
-rw-r--r-- | data/docs/11 | 47 |
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 />= != > >= < <=</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 > "2008" and released <= "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 |