diff options
Diffstat (limited to 'data/docs')
-rw-r--r-- | data/docs/11 | 207 |
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"> + <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 +<b>Design goals</b> +<ul> + <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> +</ul> +<br /> + +<b>Design overview</b> +<ul> + <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> +</ul> +<br /> + +<b>Limits</b> +<p>The following limits are enforced by the server, in order to limit the +server resources and prevent abuse of this service.</p> +<ul> + <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> +</ul> + +<br /> +<b>Test version:</b> +<dl> + <dt>Host (beta)</dt><dd>beta.vndb.org</dd> + <dt>Port</dt><dd>19534 ('VN')</dd> +</dl> + + +:SUB:Request/response syntax +<p> + The VNDB API uses the JSON format for data in various places, this document assumes + you are familiar with it. See <a href="http://json.org/">JSON.org</a> for a quick + overview and <a href="http://www.ietf.org/rfc/rfc4627.txt?number=4627">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: +</p> +<dl> + <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> +</dl> +<br /> + +<b>Message format</b> +<p> + 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. +</p> +<pre> + login {"protocol":1,"username":"ayo"}<b class="standout">0x04</b> +</pre><pre> + login { + "protocol" : 1, + "username" : "ayo" + } + <b class="standout">0x04</b> +</pre> +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> +<p> + 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: =, !=, <, <=, >, + >= 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: +</p> +<pre> + (title~"osananajimi"or(id=2)) +</pre><pre> + ( + id = 2 + or + title ~ "osananajimi" + ) +</pre> +<p>More complex things are also possible:</p> +<pre> + ((platforms = ["win", "ps2"] or languages = "ja") and released > "2009-01-10") +</pre> +<p>See the individual commands for more details.</p> + + +:SUB:The 'login' command +<pre> + login {"protocol":1,"client":"test","clientver":0.1,"username":"ayo","password":"hi-mi-tsu!"} +</pre> +<p> + 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: +</p> +<dl> + <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> +</dl> +<p> + The server replies with either 'ok' (no arguments), or 'error' (see below). +</p> + + + +:SUB:The 'error' response +<p> + 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: +</p> +<pre> + error {"id":"parse", "msg":"Invalid command or argument"} +</pre> +<p> + 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: +</p> +<dl> + <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> +</dl> + + + |