External Services and Tools/API Documentation

Introduction

All scripts are located at http://battlemaster.org/data/. So, for example, to get the region data of Akesh Temple, you would access the URL http://battlemaster.org/data/region.php?World=1&ID=1.

Request Structure

All API requests should be properly formatted HTTP GET requests, with special attention paid to the Authorization and Accept headers. All Requests on this page will include formatting details of the response along with indication on whether they require authentication or not. Requests that do not require authentication will not be affected if your application sends the Authorization header with a valid token--this header will be ignored unless needed.

Return Types

The API will always expect an Accept header declaration and will error out with an XML response if one is not provided. Acceptable Accept headers are "text/xml", "application/xml", and "application/json".

All error codes will return in the data format requested (if one is requested), and all requests will include appropriate HTTP Status Codes (usually 200, 400, or 404).

Finally, all requests will return license and metadata information.

Unauthenticated Requests

The following requests do not require use of the Authorization HTTP header. All requests require use of the Accept HTTP header to indicate return type.

• Manual Page - Access Point - Input(s) - Description
• listrealms - /data/listrealms - /{world} - Lists all realms on an island.
• listregions - /data/listregions - /{world} - Lists all regions on an island.
• region - /data/region - /{world}/{region} - List details about a particular region.
• realm - /data/realm - /{world}/{realm}/{withregions} - List details about a particular realm.
• character - /data/character - /{world}/{character} - List details about a particular character.
• family - /data/family - /{family} - List details on a particular family. Will not list characters of a family.
• active-nobles - /data/active-nobles - /{family} - Lists active nobles of a family, with family information as well.
• active-characters - /data/active-characters- /{family} - Lists active characters of a family, with family information as well.
• active-commoners - /data/active-commoners - /{family} - Lists active commoners of a family, with family information as well.
• all-commoners - /data/all-commoners - /{family} - Lists all commoners of a family, with family information as well.
• all-characters - /data/all-characters- /{family} - Lists all characters of a family, with family information as well.
• active-nobles - /data/all-nobles - /{family} - Lists all nobles of a family, with family information as well.
• globals - /data/globals- N/A - Returns the current day/night status, and time until next turn.

Additional Information

World IDs

The various game worlds of BattleMaster are internally accessed through ID numbers. Here is the mapping:

ID	World
1	East Island
2	Atamara
4	Beluaterra
6	Colonies
7	Far East
8	Dwilight

Yes, 3 and 5 are missing. They used to be the IDs of South-West and South-East Island.

Other IDs

You can query most data sets by ID number or by name. Querying by name is considerably more expensive on our database, so we strongly encourage you to locally cache the ID/Name associations that you learn. That is why all datasets return the ID.

Output Values

Many values can be empty, e.g. when the realm currently has no banker, or if a region does not belong to a duchy (i.e. an imperial region). Empty values are always returned as empty strings, e.g.:

<bankername></bankername>

Nevertheless, external tools should fail gracefully if an expected tag is missing.

XML Tree

These data scripts were written with MediaWiki's External Data extension in mind. The extension does not parse an XML tree, but simply scans for key/value pairs. Therefore, we do not generate tree structures in our output. For example, in a pure XML environment, the output for realm governments would instead be something like

<ruler>
   <name> string </name>
   <title> string </title>
</ruler>

However, since the extension does not parse the tree, the next occurrance, say within the general tag would overwrite the variables "name" and "title".

Your application must, however, recognize and parse the XML tags. We can and will change the order of the tags as we see fit without notice, so do not use an approach like "ok, 2nd entry is the name..." - always do parse the tags.