REST API

This article is a stub.

The Tygron API allows you to communicate with the Tygron Engine using third-party applications. When an external application wishes to communicate with the Tygron Engine, it does not need to interact using the browser applet. Instead, the API allows programs to access all functionality of the Tygron Engine using http requests.

The API can be accessed using a SSL secure connection, by appending the URL of the Engine with "/api/". For example:

https://www.tygronengine.com/api/

The API uses a REST architecture. By default it sends back data in human-readable HTML format, to allow for navigation of the available information and functionality. However, for external applications, information can also be requested in JSON format.

Authentication

To use the API, you must have a valid Tygron account on the server. If multiple Tygron servers are in use, you must have these credentials on the server you are trying to access. When accessing the API via the browser, you will be prompted for these credentials. The Tygron Engine uses Basic access authentication.

Authenticating against sessions

Although access to the API generally requires authentication with account credentials, sessions on the server require tokens to access. Your application must provide these in the header of the http request when attempting to access a server. For example:

serverToken: 872ad98e-9bfe-4ae1-a498-0e8ca74469ce
clientToken: 4b6af59c-0eda-49c3-ac73-56c8d2ce40f0

The server token serves as an authentication for a specific sessions. Each session has a different server token. The client token serves as a unique identifier to tell you or your application apart from other clients connected to the same session. For convenience in the browser, you can also append a query parameter "token" to your URL, to provide the proper serverToken. For example:

?token=872ad98e-9bfe-4ae1-a498-0e8ca74469ce&clientToken=4b6af59c-0eda-49c3-ac73-56c8d2ce40f0

Note that the serverToken in this case is simply called token.

Navigating the API

The api for the Tygron Engine can be reached by appending the URL for the Tygron Engine with "/api/". For example: https://www.tygronengine.com/api/

To see the full range of options available through the API, it is recommended to use your browser to access the API. You will be prompted to log in with your Tygron Engine username and password.

By default, all options and information available through the API is presented in human-readable webpages. Most information in the Tygron Engine can easily be reached by following the links on these pages.

Parts of the API can be reached directly. There is also a listing of all "slots" on the server. In each slot a session can be run. When attempting to access a session, you must be sure to provide an appropriate server token.

Data

The API provides access two 2 kidns of functionalities. It is possible to request data from the server using the API. It is also possible to fire "events" on the server. In most cases, an event triggers some process on the server (such as the start of a session or the construction of a building), although in some cases they also simply return information (such as retrieving a list of joinable sessions).

GET and POST requests

A GET request is the default type of request, and is the type of request also made by your browser. This type of request is used to retrieve data from a source, in this case from the Tygron Engine. Some data can also be returned in Json format. This can be requested by appending ?f=json to the url you are requesting data from.

POST requests are used to fire events on the server. Some events do not require any additonal input. Others require one or more parameters to be provided. When firing an event in the browser, the additonal parameters are sent using a form on the page, and an html page is returned in repsonse. It is also possible to send the additional parameters in Json format. In this case, Json is returned. See the examples below:

HTML response

HEADERS:
POST /api/services/event/IOServicesEventType/START_NEW_SESSION/ HTTP/1.1
Host: www.tygronengine.com
Content-Type: application/x-www-form-urlencoded
Accept: text/html
Authorization: Basic eW91dHJpZWR0b3NlZW15cGFzc3dvcmQ6YnV0aW1ub3R0ZWxsaW5n
Content-Length: 42

CONTENT:
0=SINGLE_PLAYER&1=delftshowcase17&2=&3=&4=

RESPONSE HEADERS:
HTTP/1.1 200 OK
Content-Type: text/html
Date: Wed, 13 May 2015 09:01:46 GMT
Content-Length: 562

JSON response

POST /api/services/event/IOServicesEventType/START_NEW_SESSION/?f=JSON HTTP/1.1
Host: www.tygronengine.com
Content-Type: application/json
Accept: application/json
Authorization: Basic eW91dHJpZWR0b3NlZW15cGFzc3dvcmQ6YnV0aW1ub3R0ZWxsaW5n
Content-Length: 35

CONTENT:
["SINGLE_PLAYER","delftshowcase17"]

RESPONSE HEADERS:
HTTP/1.1 200 OK
Content-Type: application/json
Date: Wed, 13 May 2015 09:09:56 GMT
Content-Length: 1

Note that the supplied Content-Type header must be "application/json", the Accept header must be "application/json", and the f=JSON parameters must be added to the url. Also note that when sending parameters in JSON format, optional parameters may be left out entirely.

Updates

During a session, data pertaining to a project or session can be added, changed, and deleted. For example, when a player constructs an additional building, increases their indicator's score, or dismisses a message. It is possible to listen for changes like these via the "update/" segment in a session's url structure. This mechanism works by long-polling the server, and awaiting a response.

Along in this request you must provide a JSON map, containing the types of data you are listening for, and the most recent version you have of these. An example for such a request:

HEADERS:
POST /api/slots/0/update/ HTTP/1.1
Host: www.tygronengine.com
Content-Type: application/json
Accept: application/json
serverToken: 7b9009c7-3a40-4d71-9f6d-b34928360d06
Content-Length: 32 

CONTENT:
{"SETTINGS":68, "INDICATORS":45}

If the session has a more recent version of either the settings or the indicators, it will respond immediately with a json map containing a list of updated and deleted settings and/or indicators. If no newer information is available yet, the server will wait with responding until it does have new information, or until a timeout occurs. In the latter case, an empty response will be sent back with status code 204.

Sessions

The Tygron Engine acts as a central server. On it, information regarding domains, users and projects is stored. To interact with a project (whether it's creating, editing or playing) the project must be started in the appropriate fashion on the server.

To start a session on the server, you must authenticate with appropriate credentials. You can then instruct the server to start your project in a variety of modes. After the session has started, you can request information regarding the session, including a server token with which you can interact with the session, and a client token which will serve as your unique identification to the session.

A session is automatically closed when no client interacts with it for some time. Interaction can be as simple as requesting information from the session. However, your application is recognized as an interacting client if it does so providing its client token.

Activating and closing sessions

There are multiple events involved in having your application neatly interact with a session on the server.

• IOServicesEventType.START_NEW_SESSION: This event starts a project on the server. No interaction takes place yet. If the project is already opened in Editor mode, it cannot be opened again, either in an Editor or as a playable game, until the session is closed. If the project has been opened in Single Player or Multiplayer mode, the project cannot be edited until all the playable sessions have closed.

• IOServicesEventType.GET_JOINABLE_SESSIONS: This event lists all currently running sessions which you are able to join.

• IOServicesEventType.JOIN_SESSION: This event provides you with tokens you can use to join the project. The serverToken is necessary to interact with the specific project. The clientToken identifies your program to the server, allowing it to recognize there is a client interacting with the project. If no clients interact with a project for too long, the sessions closes automatically.

• IOServicesEventType.CLOSE_SESSION: This event lets the server know your application has left the session. This means any stakeholder you have selected is freed up for another client, and the server no longer considers your client part of the session. When all clients have left a session, the session can be closed immediately, or times out after a set period.

• IOServicesEventType.KILL_SESSION: This event terminates a session immediately.

Return codes

200: Success: This means the request was accepted.

400: Bad Request: This is returned when attempting to access data or events without sufficient rights, or when trying to access a session without a valid server token.

405: Method Not Allowed: This is returned when you make an improper type of request. For example, when you make a GET request when only POST is allowed. In the returned header, you should receive a list of allowed methods.

406: Not Acceptable: This is returned when a request is made to an URL, requesting a format which cannot be returned. For example, the base URL of the api (api/) can be viewed in the browser, because it is returned in HTML, but will cause this statuscode when requested in JSON format.

500: Internal Server Error: This may be returned when the server fails to process a request. This may occur, for example, when supplied arguments are improperly formatted.