External Services and Tools/API Documentation

From BattleMaster Wiki
Jump to navigation Jump to search

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. Added in v2
  • active-commoners - /data/active-commoners - /{family} - Lists active commoners of a family, with family information as well. Added in v2
  • all-commoners - /data/all-commoners - /{family} - Lists all commoners of a family, with family information as well. Added in v2
  • all-characters - /data/all-characters- /{family} - Lists all characters of a family, with family information as well. Added in v2
  • all-nobles - /data/all-nobles - /{family} - Lists all nobles of a family, with family information as well. Added in v2
  • globals - /data/globals - N/A - Returns the current day/night status, and time until next turn.

Authenticated Requests

These requests will always require at minimum, your user ID and your Application Key. The application key must be sent as part of the Authorization HTTP header as a Bearer token.

If your Application key was 123456abcdef, for instance, your Authorization header would read: "Bearer 123456abcdef".

Any requests that do not supply valid credentials will return a HTTP Status Code 401, "Unauthorized".

  • player-data - /data/player-data - /{user ID} - Displays your player and character information, similar to your account page. Coming in v2.1

Additional Information

World IDs

The various game worlds of BattleMaster are internally accessed through ID numbers. If you interested in efficiency, IDs are checked for first. 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.

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.

Retrieved from "https://wiki.battlemaster.org/index.php?title=External_Services_and_Tools/API_Documentation&oldid=211209"