:TITLE:Public Database API
This API is currently in development, pretty much everything is subject to change without notice.
The following limits are enforced by the server, in order to limit the server resources and prevent abuse of this service.
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:
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" } 0x04The 0x04 byte will be ommitted in the other examples in this document. It is however still required.
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' commandlogin {"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:
The server replies with either 'ok' (no arguments), or 'error' (see below).
:SUB:The 'error' responseEvery 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: