idGames Archive Public API
Version 2
Updated: 1/6/2014
Introduction

The idGames Public API is an HTTP-driven programming interface that allows outside clients to read the contents of the idGames database, putting Doom-community-driven applications into the hands of developers, and from their hands into the public!

The API can be called in several ways, as long as each of those ways can read an HTTP response, such as through a web browser. Each call to the API is done though the api.php page, which returns a document containing the desired information.

Calling the API

All calls to the API involve sending a command to api.php via the action parameter, along with any other required parameters, if any. The page returned contains parseable information for each command call, specified below. All calls can be made with either GET or POST HTTP requests.

The data retrieved from the API can be either XML or JSON. All returned data in XML is encoded as UTF-8. All requests should be sent encoded as UTF-8 if possible.

API Specification

Below is a listing of every conceivable call that one can make to the API.

All calls, if returned as XML, are returned in an idgames-response element, which contains additional child elements.

All calls, if returned as JSON, are returned as a single object that contains child members.

All calls take the following parameters:

Parameter Optional? Notes
action No The name of the action to call.
out Yes The output format. If not specified, or not an accepted value, assumes "xml". Accepted values are:
xml, json

For Example:
XML: api.php?action=ping
JSON: api.php?action=ping&out=json

The version number of the response is sent back in two different ways, which depends on the specified output type.

In XML, the version is an attribute on idgames-response. In JSON, it is a member of the response object, as part of a member called "meta" which contains metainfo about the response. The version is in this object under the "version" member.

IMPORTANT: Since January 2nd, 2014, the version number is in integers, not floating point. Apologies if this ruins implementations!

All responses, version 2 and earlier, take this form:

Element Always Present? Notes
meta JSON Only Meta info about the response.
version
Yes Response version.
content No The content of the command return. Present on successful calls.
error No Error message element. Present if an error occurred on the command call.
type
Yes The type of error.
message
Yes The error message.
warning No Warning message element. Present if the caller should know additional info, but the call did not produce an error.
type
Yes The type of warning.
message
Yes The warning message.
Action Commands

Below is a description of all action types, and what they could conceivably return. The action name is passed via the action parameter.

ping

Sends back "true". This is just for testing if the server hosting this API is up.

Takes no additional parameters.

Response (Content):

Element Always Present? Notes
status Yes Contains "true".

For Example:
XML: api.php?action=ping
JSON: api.php?action=ping&out=json

dbping

Sends back "true" if the database connection is active. Returns an error if not.

Takes no additional parameters.

Response (Content):

Element Always Present? Notes
status Yes Contains "true".

For Example:
XML: api.php?action=dbping
JSON: api.php?action=dbping&out=json

about

Sends back info about the API.

Takes no additional parameters.

Response (Content):

Element Always Present? Notes
credits Yes Who made this awesome thing possible.
copyright Yes Copyright information regarding this API.
info Yes Additional info.

For Example:
XML: api.php?action=about
JSON: api.php?action=about&out=json

get

Sends back information about a file entry in idGames, including reviews and votes, but not who made them (unless they signed their reviews, obviously). Please note that most, if not all of the returned data is taken from the file's accompanying text file when it was added to the archive, so any data that appears to be in error could be coming from a non-standard TXT.

Addt'l Parameters:

Parameter Optional? Notes
id Depends The file id. If not present, must use file.
file Depends The file path. If not present, must use id. Since Version 2

Response (Content):

Element Always Present? Notes
id Yes The file's id.
title Yes The title of the file.
dir Yes The file's full directory path.
filename Yes The filename itself, no path.
size Yes The size of the file in bytes.
age Yes The date that the file was added in seconds since the Unix Epoch (Jan. 1, 1970). Note: This is likely influenced by the time zone of the primary idGames Archive.
date Yes A YYYY-MM-DD formatted date describing the date that this file was added to the archive.
author Yes The file's author/uploader.
email Yes The author's E-mail address.
description Yes The file's description.
credits Yes The file's additional credits.
base Yes The file's base (from another mod? made from scratch?).
buildtime Yes The file's/WAD's build time.
editors Yes The editors used to create this.
bugs Yes Known bugs (if any).
textfile Yes The file's text file contents.
rating Yes The file's average rating, as rated by users.
votes Yes The number of votes that this file received.
url Yes The URL for the idGames Archive page for this file.
idgamesurl Yes The idgames protocol URL for this file.
reviews Yes The element that contains all reviews for this file in review elements.
review
No The individual review. Can return many.
text
Yes The individual review's text, if any. Note: may be blank.
vote
Yes The vote associated with the review.

Possible Responses (Error):

Type Message Raised If
Bad Id No file associated with that id (ID). A file is not associated with the provided id.
Bad File No file associated with that path (FILE). A file is not associated with the provided path.

For Example:
XML: api.php?action=get&id=15156
JSON: api.php?action=get&id=15156&out=json

getparentdir

Returns the parent directory of the specified directory.

Addt'l Parameters:

Parameter Optional? Notes
id Depends The directory id. If not present, must use name.
name Depends The directory name (in full). If not present, must use id.

Response (Content):

Element Always Present? Notes
id Yes Id of the parent directory.
name Yes Name of the parent directory.

Possible Responses (Error):

Type Message Raised If
Missing Parameter Missing required parameter: id OR name. id or name is not specified.
Bad Id No directory associated with that id (X). A diectory is not associated with the provided id.
Bad Name No directory associated with that name (X). A diectory is not associated with the provided name.

Possible Responses (Warning):

Type Message Raised If
No Parent Directory does not have a parent. If the directory associated with id or name is a root directory.

For Example:
XML: api.php?action=getparentdir&id=17
JSON: api.php?action=getparentdir&id=17&out=json

For Example:
XML: api.php?action=getparentdir&name=levels/doom/a-c/
JSON: api.php?action=getparentdir&name=levels/doom/a-c/&out=json

getdirs

Returns the directories under the specified directory. If no directory is specified, then this returns all directories off of the root.

Addt'l Parameters:

Parameter Optional? Notes
id Yes The directory id.
name Yes The directory name (in full). Takes precedence over id.

Response (Content):

Element Always Present? Notes
dir No Directory element. Can return many.
id
Yes Id of the directory.
name
Yes Name of the directory.

Possible Responses (Error):

Type Message Raised If
Bad Id No directory associated with that id (X). A diectory is not associated with the provided id.
Bad Name No directory associated with that name (X). A diectory is not associated with the provided name.

Possible Responses (Warning):

Type Message Raised If
No Directories No directories are under this directory. If the directory associated with id or name is a leaf directory, or doesn't exist.

For Example:
XML: api.php?action=getdirs&name=levels/doom/
JSON: api.php?action=getdirs&name=levels/doom/&out=json

getfiles

Returns the files under the specified directory. Please note that most, if not all of the returned data is taken from the file's accompanying text file when it was added to the archive, so any data that appears to be in error could be coming from a non-standard TXT.

Addt'l Parameters:

Parameter Optional? Notes
id Depends The directory id. If not present, must use name.
name Depends The directory name (in full). If not present, must use id.

Response (Content):

Element Always Present? Notes
file No File element. Can return many.
id
Yes The file's id.
title
Yes The title of the file.
dir
Yes The file's full directory path.
filename
Yes The filename itself, no path.
size
Yes The size of the file in bytes.
age
Yes The date that the file was added in seconds since the Unix Epoch (Jan. 1, 1970). Note: This is likely influenced by the time zone of the primary idGames Archive.
date
Yes A YYYY-MM-DD formatted date describing the date that this file was added to the archive.
author
Yes The file's author/uploader.
email
Yes The author's E-mail address.
description
Yes The file's description.
rating
Yes The file's average rating, as rated by users.
votes
Yes The number of votes that this file received.
url
Yes The URL for the idGames Archive page for this file.
idgamesurl
Yes The idgames protocol URL for this file.

Possible Responses (Error):

Type Message Raised If
Missing Parameter Missing required parameter: id OR name. id or name is not specified.
Bad Id No directory associated with that id (X). A diectory is not associated with the provided id.
Bad Name No directory associated with that name (X). A diectory is not associated with the provided name.

Possible Responses (Warning):

Type Message Raised If
No Files No files are under this directory. If the directory associated with id or name is a leaf directory, or doesn't exist.

For Example:
XML: api.php?action=getfiles&name=levels/doom/megawads/
JSON: api.php?action=getfiles&name=levels/doom/megawads/&out=json

getcontents

Returns the files and directories under the specified directory. Please note that most, if not all of the returned data from files is taken from the file's accompanying text file when it was added to the archive, so any data that appears to be in error could be coming from a non-standard TXT.

Addt'l Parameters:

Parameter Optional? Notes
id Depends The directory id. If not present, must use name.
name Depends The directory name (in full). If not present, must use id.

Response (Content):

Element Always Present? Notes
file No File element. Can return many.
id
Yes The file's id.
title
Yes The title of the file.
dir
Yes The file's full directory path.
filename
Yes The filename itself, no path.
size
Yes The size of the file in bytes.
age
Yes The date that the file was added in seconds since the Unix Epoch (Jan. 1, 1970). Note: This is likely influenced by the time zone of the primary idGames Archive.
date
Yes A YYYY-MM-DD formatted date describing the date that this file was added to the archive.
author
Yes The file's author/uploader.
email
Yes The author's E-mail address.
description
Yes The file's description.
rating
Yes The file's average rating, as rated by users.
votes
Yes The number of votes that this file received.
url
Yes The URL for the idGames Archive page for this file.
idgamesurl
Yes The idgames protocol URL for this file.
dir No Directory element. Can return many.
id
Yes Id of the directory.
name
Yes Name of the directory.

Possible Responses (Error):

Type Message Raised If
Missing Parameter Missing required parameter: id OR name. id or name is not specified.
latestvotes

Returns the latest votes submitted, date descending.

Addt'l Parameters:

Parameter Optional? Notes
limit Yes The amount to return. If not specified, or is too large, assumes the maximum allowed.

Response (Content):

Element Always Present? Notes
vote No Vote element. Can return many.
id
Yes Id of the vote.
file
Yes Id of the file voted on.
title
Yes The title of the file voted on.
rating
Yes The file's average vote.
text
Yes The text of the review, if any.

Possible Responses (Warning):

Type Message Raised If
Limit Warning Limit was too large. Changed to X. If the limit specified was too large.

For Example:
XML: api.php?action=latestvotes&limit=10
JSON: api.php?action=latestvotes&limit=10&out=json

latestfiles

Returns the latest files submitted, date descending.

Addt'l Parameters:

Parameter Optional? Notes
limit Yes The amount to return. If not specified, or is too large, assumes the maximum allowed.
startid No If specified, this is the file id to start from instead of the latest id.

Response (Content):

Element Always Present? Notes
file No File element. Can return many.
id
Yes Id of the file.
title
Yes The title of the file.
author
Yes The file's author.
description
Yes The file's description.
rating
Yes The file's average rating, as rated by users.

Possible Responses (Warning):

Type Message Raised If
Limit Warning Limit was too large. Changed to X. If the limit specified was too large.

For Example:
XML: api.php?action=latestfiles&limit=10
JSON: api.php?action=latestfiles&limit=10&out=json

search

Searches through the database for files matching a query string. There is a limit to how much is returned. Please note that most, if not all of the returned data is taken from the file's accompanying text file when it was added to the archive, so any data that appears to be in error could be coming from a non-standard TXT.

Addt'l Parameters:

Parameter Optional? Notes
query No The query string to use. Must be at least 3 characters long.
type Yes The type of search. If not specified, assumes filename. Must be one of the following:
filename, title, author, email, description, credits, editors, textfile
sort Yes The type of sorting. If not specified, assumes date. Must be one of the following:
date, filename, size, rating
dir Yes The sorting direction. If not specified, assumes asc. Must be one of the following:
asc, desc

Response (Content):

Element Always Present? Notes
file No File element. Can return many.
id
Yes The file's id.
title
Yes The title of the file.
dir
Yes The file's full directory path.
filename
Yes The filename itself, no path.
size
Yes The size of the file in bytes.
age
Yes The date that the file was added in seconds since the Unix Epoch (Jan. 1, 1970). Note: This is likely influenced by the time zone of the primary idGames Archive.
date
Yes A YYYY-MM-DD formatted date describing the date that this file was added to the archive.
author
Yes The file's author/uploader.
email
Yes The author's E-mail address.
description
Yes The file's description.
rating
Yes The file's average rating, as rated by users.
votes
Yes The number of votes that this file received.
url
Yes The URL for the idGames Archive page for this file.
idgamesurl
Yes The idgames protocol URL for this file.

Possible Responses (Error):

Type Message Raised If
Missing Argument Missing required parameter: query The query string is not provided.
Query Too Small Query string is too small. Must be at least 3 characters. The query string is not long enough.

Possible Responses (Warning):

Type Message Raised If
No Results No files returned for query X. If the search yields no results.
Limit Warning Result limit reached. Returning X files. If the search would return more files than the limit.

For Example:
XML: api.php?action=search&query=chest&type=filename&sort=date
JSON: api.php?action=search&query=chest&type=filename&sort=date&out=json