:TITLE:Public Database API

IN DEVELOPMENT

This API is currently in development, pretty much everything is subject to change without notice.

:INC:index :SUB:Introduction Design goals
Design overview
Limits

The following limits are enforced by the server, in order to limit the server resources and prevent abuse of this service.


Test version:
Host (beta)
beta.vndb.org
Port
19534 ('VN')
: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 JSON.org for a quick overview and RFC 4627 for the glory details.

The words object, array, value, string, number and int refer to the JSON data types. In addition the following definitions are used in this document:

request or command
Message sent from the client to the server.
response
Message sent from the server to the client.
whitespace
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.
date
A string 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 null is used.

Message format

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.
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.
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"}0x04
 login {
  "protocol" : 1,
  "username" : "ayo"
 }
 0x04
The 0x04 byte will be ommitted in the other examples in this document. It is however still required.

Filter string syntax

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 expressions, 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.
An expression consists of a field name, followed by an operator and a value. 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 value can be any valid JSON value. Whitespace characters are allowed, but not required, between all expressions, field names, operators and values.
The following two filters are equivalent:

 (title~"osananajimi"or(id=2))
 (
   id = 2
   or
   title ~ "osananajimi"
 )

More complex things are also possible:

 ((platforms = ["win", "ps2"] or languages = "ja") and released > "2009-01-10")

See the individual commands for more details.

: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:

protocol
An integer that indicates which protocol version the client implements. Must be 1.
client
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.
clientver
A positive number indicating the software version of the client.
username
String containing the username of the person using the client.
password
String, password of that user in plain text.

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:

parse
Syntax error or unknown command.
missing
A JSON object argument is missing a required member. The name of which is given in the additional "field" member.
badarg
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.
needlogin
Need to be logged in to issue this command.
auth
(login) Incorrect username/password combination.
loggedin
(login) Already logged in. Only one successful login command can be issues on one connection.
sesslimit
(login) Too many open sessions for the current user.
gettype
(get) Unknown type argument to the 'get' command.
getinfo
(get) Unknown info flag to the 'get' command. The name of the unrecognised flag is given in an additional "flag" member.
filter
(get) Unknown filter field or invalid combination of field/operator/argument type. Includes three additional members: "field", "op" and "value" of the incorrect expression.