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.
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.
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. |
Below is a description of all action types, and what they could conceivably return.
The action name is passed via the action parameter.
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
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
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
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. |
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. |
| 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. |
| username | Yes | The user name associated with the review, if any. Note: may be blank/null, which means "Anonymous". Since Version 3 |
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
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
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
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. |
| 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
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. |
| 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. |
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
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
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. |
| 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. |