HAPI

The Hyperiums API (HAPI) is a web service that provides access to game world data from the game Hyperiums. Communication is done over simple HTTP GET requests.

Note: Throughout this document, the placeholder <HAPI> will be used as shorthand for the HAPI URL, which is:

http://www.hyperiums.com/servlet/HAPI

Overview

HTTP Requests

All requests are HTTP GET requests that contain query string parameters.

HTTP Responses

Each response contains name/value pairs in the form of a query string. For example:

dummy=&planet0=Fayette&planetid0=91338&nbexp0=50&inpipe0=0&tobedem0=0&nbonsale0=0&sellprice0=0&rentability0=0

Note that HAPI does not encode most special characters, such as spaces, equal signs, and question marks, so be careful if you are using a generic URL parsing library.

Escaped ampersand characters appear as [:&:].

Content Type

Responses to the Download request have the content type application/download, unless an error response is returned, in which case the content type is text/plain.

Responses to all other requests have the content type text/plain.

Error Responses

If an error occurs with a request, such as an authentication failure, a response containing an error parameter will be returned. For example:

error=authentication failed

This includes the Download request, which normally returns a gzipped file.

Lists

Many responses return lists of data. Because each parameter name in a query string has to be unique, the name of each parameter is appended with an index number.

Some responses also have sub-lists. The parameter names for sub-lists are appended with the parent list index, a period, and then the child list index. For example, the GetFleetsInfo method returns a list of planets, each of which contains a list of fleets:

planet0=Fayette&...fname0.0=AlphaDogs&owner0.0=mangst&...fname0.1=TheWolves&owner0.1=?...planet1=Spruce...

Boolean values

Some response parameters contain boolean values. A value of "0" means "false" and a value of "1" means "true".

Timestamps

All timestamps from the server are in GMT and are in the following 24-hour format:

yyyy-mm-dd hh:mm:ss

"dummy" parameter

An empty parameter named dummy is returned in some responses. This is probably included to show that the request was processed successfully incase the response has no data to return (a completely empty response could mean that there was a server error).

"failsafe" parameter

A query string parameter named failsafe can optionally be included in the request. The value of this parameter can be anything, but it should be unique so that no two requests use the same value. If included in the request, a failsafe parameter with the same value will be sent back in the response (it is "echoed" back).

This can be used to ensure that the response is coming directly from the HAPI server, and not from a cache. The value included in the response should match the original value sent in the request. If they are different (or if the response does not contain a failsafe parameter at all), then the response should be discarded, as it may not contain up-to-date data.

Request/response example:

Request URL

<HAPI>?request=games&failsafe=1322699724

Response Body

dummy=&game0=Hyperiums6&state0=1&...&failsafe=1322699724

Authentication

In order to access player-centric information in HAPI, you must first authenticate with the player’s account. This involves the player logging into Hyperiums him or herself and generating a "HAPI key" also known as an "external authentication key". A HAPI key is generated by going to "Preferences > Authentication".

After the HAPI key is generated, authentication with HAPI can proceed. An authentication request and response can be described as follows:

Request/response example:

Request URL

<HAPI>?game=Hyperiums6&player=mangst&hapikey=c788c4fdecd3e8aa1

Response Body

gameid=0&playerid=143057&playername=mangst&authkey=214595267&servertime=2011-06-05 00:44:38

Request parameters:

• game The name of the game to connect to (the Games request can be used to get a list of all games--it does not require authentication).
• player The player's username.
• hapikey The HAPI key generated from the web site.

Response parameters:

• gameid The ID of the game (must be included in all subsequent requests).
• playerid The ID of the player (must be included in all subsequent requests).
• authkey The authentication key (must be included in all subsequent requests). This is not the same as the HAPI key.
• playername The player's username.
• servertime The time that the authentication took place.

The gameid, playerid and authkey response parameters must be included in all subsequent HAPI requests.

All requests except for the Games and Download requests require this kind of authentication (Download requires the username/password to be sent, Games requires no authentication).

When the player logs out of his or her web session from the hyperiums.com website, the HAPI session is also terminated. A new HAPI key will have to be generated in order to connect to HAPI again.

TODO: Requests and Constants sections.