Introduction

TIGdb provides programmatic access to its data via an Application Programming Interface (API). This document is a reference for that functionality, and aims to serve as a reference for developers building tools that talk to TIGdb.

Overview

The TIGdb API attempts to conform to the design principles of Representational State Transfer (REST). You’ll find that you can simply change the file extension on most any request to get results in the format of your choice. We currently support three data formats: XML, JSON, and the RSS syndication formats.

For example, if you're on the page:

http://db.tigsource.com/games/cave-story

You can add the extension .xml or .json to get the respective format representation of Cave Story:

http://db.tigsource.com/games/cave-story.xml
http://db.tigsource.com/games/cave-story.json

Similarly, this works for listing pages, with the addition of the .rss format. You can also include the query parameters that are added when filtering games, as well as special parameters page and only. Here are some examples:

http://db.tigsource.com/browse.xml?platform=linux&max-price=0
http://db.tigsource.com/top.rss?developer=cactus
http://db.tigsource.com/top.json?page=2
http://db.tigsource.com/browse.xml?only=id+shortname+updated-at

Unless it's not obvious, only will filter what fields are included in the data structure returned. In that last example, we get only the game ID, shortname, and the timestamp it was last updated. This can be useful for expiring caches for instance, but also just to speed up requests since we're pretty verbose by default.

Pagination

You'll notice we still paginate the results like we do on the website. You can use the page query parameter to specify which page you want like in the above examples. While Atom provides extensions to support pagination information, we provide pagination information for all requests (in all formats) that have pagination... including the HTML representation. We provide this information through these HTTP response headers:

• TIGdb-Page-Current - The current page you're on (as defined by the page query parameter or the default of 1)
  
• TIGdb-Page-Count - The number of pages there are
• TIGdb-Page-Size - The maximum number of results on a page
• TIGdb-Result-Count - The total number of results across all pages
  

Resources

Games are just one of the types of resources we expose with this API. We expose the following resources with the given formats at these URLs:

Games
Formats: XML, JSON
Paths:
/games/shortname.format

Game Listings
Formats: XML, JSON, RSS
Paths:
/browse.format
/top.format
/recent.format

Developers
Formats: XML, JSON
Paths:
/developers/shortname.format

Users
Formats: XML, JSON
Paths:
/users/username.format