path: root/data/docs
diff options
authorYorhel <>2009-11-03 22:15:57 +0100
committerYorhel <>2009-11-04 20:57:02 +0100
commiteb093ac9fe5d9dcbde98c92ba2720749bb814def (patch)
tree57fd8ab3443a483b6addeafda954808663992d16 /data/docs
parent6576cf8921cbb6e8e50717e071e3f3201c088763 (diff)
API: Initial commit of the W.I.P. public API
d11 does not fully reflect what has been implemented, and things are likely to change.
Diffstat (limited to 'data/docs')
1 files changed, 207 insertions, 0 deletions
diff --git a/data/docs/11 b/data/docs/11
new file mode 100644
index 00000000..7927182b
--- /dev/null
+++ b/data/docs/11
@@ -0,0 +1,207 @@
+:TITLE:Public Database API
+<div class="warning">
+ <p>This API is currently in development, pretty much everything is subject to change without notice.</p>
+<b>Design goals</b>
+ <li>
+ Simple in implementation of both client and server. "Simple" here means that
+ it shouldn't take much code to write a secure and full implementation and that
+ client applications don't require huge dependency trees just to use this API.
+ </li>
+ <li>Powerful: Not as powerful as raw SQL, but not as rigid as commonly used REST or RPC protocols.</li>
+ <li>Fast: minimal bandwidth overhead</li>
+ <li>
+ High-level: nobody is interested in the internal database structure of VNDB
+ (ok, maybe you are, but you wouldn't want to write an application using it: it
+ changes quite often)
+ </li>
+ <li>Stateful</li>
+<br />
+<b>Design overview</b>
+ <li>TCP-based, all communication between the client and the server is done
+ using one TCP connection. This connection stays alive until it is explicitely
+ closed by either the client or the server.</li>
+ <li>Request/response, client sends a request and server replies with a response.</li>
+ <li>Session-based: clients are required to login before issuing commands to
+ the server. A session is created by issuing the 'login' command, this session
+ stays valid for the lifetime of the TCP connection.</li>
+ <li><b>Everything</b> sent between the client and the server is encoded in UTF-8.</li>
+<br />
+<p>The following limits are enforced by the server, in order to limit the
+server resources and prevent abuse of this service.</p>
+ <li>5 connections per IP. All connections that are opened after reaching this limit will be immediately closed.</li>
+ <li>3 connections per user. The login command will reply with a 'sesslimit' error when reaching this limit.</li>
+ <li><i>more to come...</i></li>
+<br />
+<b>Test version:</b>
+ <dt>Host (beta)</dt><dd></dd>
+ <dt>Port</dt><dd>19534 ('VN')</dd>
+:SUB:Request/response syntax
+ The VNDB API uses the JSON format for data in various places, this document assumes
+ you are familiar with it. See <a href=""></a> for a quick
+ overview and <a href="">RFC 4627</a>
+ for the glory details.
+ <br /><br />
+ The words <i>object</i>, <i>array</i>, <i>value</i>, <i>string</i>,
+ <i>number</i> and <i>int</i> refer to the JSON data types. In addition the following
+ definitions are used in this document:
+ <dt><i>request</i> or <i>command</i></dt><dd>
+ Message sent from the client to the server.
+ </dd><dt><i>response</i></dt><dd>
+ Message sent from the server to the client.
+ </dd><dt><i>whitespace</i></dt><dd>
+ Any sequence of the following characters: space, tab, line feed and carriage
+ return. (hexadecimal: 20, 09, 10, 0D, respectively). This is in line with the
+ definition of whitespace in the JSON specification.
+ </dd><dt><i>date</i></dt><dd>
+ A <i>string</i> signifying a date (in particular: release date). The
+ following formats are used: "yyyy" (when day and month are unknown), "yyyy-mm"
+ (when day is unknown) "yyyy-mm-dd", and "tba" (To Be Announced). If the year is
+ not known and the date is not "tba", the special value <b>null</b> is used.
+ </dd>
+<br />
+<b>Message format</b>
+ A message is formatted as a command or response name, followed by any number of
+ arguments, followed by the End Of Transmission character (04 in hexadecimal).
+ Arguments are separated by one or more whitespace characters, and any sequence
+ of whitespace characters is allowed before and after the message.<br />
+ The command or response name is an unescaped string containing only lowercase
+ alphabetical ASCII characters, and indicates what kind of command or response
+ this message contains.<br />
+ An argument can either be an unescaped string (not containing whitespace), any
+ JSON value, or a filter string. The following two examples demonstrate a
+ 'login' command, with an object as argument. Both messages are equivalent, as
+ the whitespace is ignored. '0x04' is used to indicate the End Of Transmission
+ character.
+ login {"protocol":1,"username":"ayo"}<b class="standout">0x04</b>
+ login {
+ "protocol" : 1,
+ "username" : "ayo"
+ }
+ <b class="standout">0x04</b>
+The 0x04 byte will be ommitted in the other examples in this document. It is
+however still required.<br />
+<br />
+<b>Filter string syntax</b>
+ Some commands accept a filter string as argument. This argument is formatted
+ similar to boolean expressions in most programming languages. A filter consists
+ of one or more <i>expressions</i>, separated by the boolean operators "and" and
+ "or" (lowercase). Each filter expression can be surrounded by parentheses to
+ indicate precedence, the filter argument itself must be surrounded by parentheses.
+ <br />
+ An <i>expression</i> consists of a <i>field name</i>, followed by an
+ <i>operator</i> and a <i>value</i>. The field name must consist entirely of
+ lowercase alphanumeric characters and can also contain an underscore. The
+ operator must be one of the following characters: =, !=, &lt;, &lt;=, &gt;,
+ &gt;= or ~. The <i>value</i> can be any valid JSON value. Whitespace
+ characters are allowed, but not required, between all expressions, field names,
+ operators and values.<br />
+ The following two filters are equivalent:
+ (title~"osananajimi"or(id=2))
+ (
+ id = 2
+ or
+ title ~ "osananajimi"
+ )
+<p>More complex things are also possible:</p>
+ ((platforms = ["win", "ps2"] or languages = "ja") and released > "2009-01-10")
+<p>See the individual commands for more details.</p>
+:SUB:The 'login' command
+ login {"protocol":1,"client":"test","clientver":0.1,"username":"ayo","password":"hi-mi-tsu!"}
+ Every client is required to login before issuing other commands. The login
+ command accepts a JSON object as argument. This object must have the following members:
+ <dt>protocol</dt><dd>An integer that indicates which protocol version the client implements. Must be 1.</dd>
+ <dt>client</dt><dd>
+ A string identifying the client application. Between the 3 and 50 characters,
+ must contain only alphanumeric ASCII characters, space, underscore and hyphens.
+ When writing a client, think of a funny (unique) name and hardcode it into
+ your application.
+ </dd><dt>clientver</dt><dd>A positive number indicating the software version of the client.</dd>
+ <dt>username</dt><dd>String containing the username of the person using the client.</dd>
+ <dt>password</dt><dd>String, password of that user in plain text.</dd>
+ The server replies with either 'ok' (no arguments), or 'error' (see below).
+:SUB:The 'error' response
+ Every command to the server can receive an 'error' response, this response has one
+ argument: a JSON object containing at least a member named "id", which identifies
+ the error, and a "msg", which contains a human readable message explaining what
+ went wrong. Other members are also possible, depending on the value of "id".
+ Example error message:
+ error {"id":"parse", "msg":"Invalid command or argument"}
+ Note that the value of "msg" is not directly linked to the error identifier:
+ the message explains what went wrong in more detail, there are several
+ different messages for the same id. The following error identifiers are currently
+ defined:
+ <dt>parse</dt><dd>Syntax error or unknown command.</dd>
+ <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>auth</dt><dd>(login) Incorrect username/password combination.</dd>
+ <dt>loggedin</dt><dd>(login) Already logged in. Only one successful login command can be issues on one connection.</dd>
+ <dt>sesslimit</dt><dd>(login) Too many open sessions for the current user.</dd>
+ <dt>gettype</dt><dd>(get) Unknown type argument to the 'get' command.</dd>
+ <dt>getinfo</dt><dd>(get) Unknown info flag to the 'get' command. The name of the unrecognised flag is given in an additional "flag" member.</dd>
+ <dt>filterop</dt><dd>(get) Bad operator in filter expression for the field/value combination. Includes three additional members: "field", "op" and "value" of the incorrect expression.</dd>
+ <dt>filterval</dt><dd>(get) Wrong type or format for the value in a filter expression. Adds same three members as the 'filterop' error.</dd>
+ <dt>filterfield</dt><dd>(get) Unknown field in filter expression. Adds same three members as the 'filterop' error.</dd>