From c7ff7086534cd9de7ce4043eb10c7161401c1b96 Mon Sep 17 00:00:00 2001
From: Yorhel <git@yorhel.nl>
Date: Sat, 14 Nov 2009 12:57:14 +0100
Subject: d11: Finalized API documentation

---
 data/docs/11 | 47 ++++++++++++++++++++++++++++++++++++-----------
 1 file changed, 36 insertions(+), 11 deletions(-)

(limited to 'data/docs')

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
-- 
cgit v1.2.3