The viewgame API

The viewgame API lets applications retrieve IFDB's listing data for a game in the Treaty of Babel's iFiction XML format.

Identifying a game

There are two main ways to identify a game for the purposes of this API: by TUID, and by IFID.

A TUID is an IFDB-specific identifier assigned when a new IFDB game listing is created. A TUID is unique within IFDB, and never changes (it will always be the same as long as the listing exists). TUIDs generally are only meaningful within IFDB, so the most likely source of a TUID in a client application would be another IFDB service, such as the search API.

An IFID is an identifier defined by the Treaty of Babel. The key thing about IFIDs is that you can generally find a game's IFID if you have a copy of the game's story file (i.e., the byte-code file for a virtual machine system like the Z Machine, TADS, or Hugo, or simply an executable file for games created without VM systems). For games created after the Babel spec was created, the IFID generally takes the form of a standard UUID, randomly generated by the authoring system when the game is created and stored in the story file in a format-specific manner. Most of the major IF systems define an algorithm for reliably extracting this UUID given a story file. Before Babel, none of the systems had anything specifically UUID-like, so for "legacy" games, Babel instead defines format-specific algorithms for synthesizing a unique identifier from a story file. Combined, these before-and-after rules cover virtually all story files, which means that if you have a copy of a story file, you can get an IFID. So given a story file, you can directly look up the game's IFDB listing data using this API.

Protocol

The viewgame API is implemented as an http XML web service. To invoke the API, you construct a URL that encodes the game's identifier (see above) and send it to IFDB with an http GET request. IFDB replies with an XML content body containing an extended iFiction record. By extended, we mean that the record contains the standard iFiction elements, plus some custom IFDB-specific extensions.

To retrieve data by TUID, use this URL:

  https://ifdb.org/viewgame?ifiction&id=TUID

To retrieve data by IFID, use this URL:

  https://ifdb.org/viewgame?ifiction&ifid=IFID

True iFiction records vs. IFDB data

It's important to understand that the XML file returned from the viewgame API is in the form of an iFiction record, but it's not the "true" iFiction record for the game.

The true iFiction record for a game is the one provided by the game's author, or by an archivist or other authoritative third party if the author hasn't provided one. The iFiction returned from the viewgame API, in contrast, is a copy of the IFDB listing data for the game, formatted as an iFiction record. IFDB doesn't store the official iFiction for a game anywhere, and it doesn't have any automatic way to synchronize its data with the official iFiction record for a game. On the contrary, IFDB listings are editable by all IFDB members, Wiki-style, so a listing might have information beyond or different from what the author would have entered. The contents might therefore diverge from the official iFiction data provided by the author.

For post-Babel games, the author's official iFiction record can be embedded directly in the story file. If you retrieve an iFiction record for a game from IFDB, and compare it to the iFiction record embedded in the game's story file, you might well find differences. This isn't an error; it simply reflects the different origins of the respective records.

Reply format

On error, the reply has this structure:

   <viewgame xmlns="http://ifdb.org/api/xmlns">
     <errorCode>code</errorCode>
     <errorMessage>Error message text</errorMessage>
   </viewgame>

The error code is a string indicating the specific type of error that occurred:

• badRequest: invalid request format (usually, this means that no TUID or IFID was specified)
• notFound: the specified game isn't in the database
• versionNotFound: the requested listing version doesn't exist
• dbError: a database error occurred on the server

The error message text is a human-readable error message. This is the message that the regular game listing page viewer would have displayed for the same error condition, which might or might not be suitable for display in your application.

On success, the reply is in the form of a Babel iFiction record. The following fields are included, to the extent the corresponding data are present in the listing:

• identification
  • ifid
  • bafn
  • format
• bibliographic
  • title
  • author
  • language
  • firstpublished
  • genre
  • description
  • series
  • seriesnumber
  • forgiveness
• contact
  • url

In addition, the following IFDB extensions are included. The extensions are all grouped under a single <ifdb> tag that appears at the same XML nesting level as <identification>, <bibliographic>, etc (that is, as a direct child of the <story> element). The structure is as follows:

   <ifdb xmlns="http://ifdb.org/api/xmlns">
     <tuid>TUID</tuid>
     <link>URL to game page</link>
     <coverart>
       <url>URL to cover art image</url>
     </coverart>
     <averageRating>Average user rating</averageRating>
     <starRating>Star rating</starRating>
     <ratingCountAvg>Number of ratings included in the average</ratingCountAvg>
     <ratingCountTot>Total number of ratings</ratingCountTot>
   </ifdb>

The TUID is the game's IFDB internal identifier (see above).

The link element gives the URL to the main IFDB listing page for the game.

The coverart element is included only if the IFDB listing include a cover art image; if so, the url element gives an http URL to the image. This URL yields an image file (JPEG, GIF, or PNG) containing the full-size cover art image for the game. You can retrieve a thumbnail of this image by appending &thumbnail=WxH to the URL, where W and H are the desired width and height, in pixels, of the thumbnail. The server preserves the original aspect ratio of the image by treating the given dimensions as a bounding rectangle, and shrinking the image to fit these bounds.

The averageRating element provides the average IFDB member rating as a decimal floating-point number, such as "3.575". This is a simple arithmetic average of the ratings for the game entered by IFDB users; each user rating is simply an integer from 1 to 5. The starRating element provides the average value rounded to the nearest half-star, which is what IFDB usually displays on its own generated pages. IFDB usually uses a graphic image showing the number of stars in the average, and it only has an image for each half-star increment, so it has to round for this kind of display. It'd be easy enough for client code to do the rounding itself, but the API provides the rounded value anyway because this eliminates any guesswork about the exact rounding rules for boundary cases, ensuring that a client can always display the same rounded value IFDB itself does.

The ratingCountAvg and ratingCountTot elements provide the number of ratings that went into the average, and the total number of ratings for the game, respectively. The reason these are stated separately is that a user can opt to exclude her rating for a given game from the game's average. If a user exercises this option, the rating will be recorded but won't be used to compute the average. This means that the ratingCountTot value is always equal to or greater than the ratingCountAvg value.

The returned iFiction record also includes the colophon element, which identifies how the record was generated. For the purposes of the colophon, the API identifies itself with the generator name "ifdb.org/viewgame".

IFDB Home | Contact Us | Code of Conduct | Terms of Service | Privacy | Copyrights & Trademarks | API

IFDB is managed by the Interactive Fiction Technology Foundation. It is funded by the donations of IF supporters like you. All donations go to support the operation of this web site and IFTF's other services.