REST API
What is the API?
An API (Application Programmers Interface) is a feature in software which allows external parties to create applications to interact with the software. Where human users make use of a graphical interface, applications can send and receive data packages directly, in some form, when communicating via an API. An API is most useful to a technical users, as the ability to create or configure your own software is implicitly required.
How does the API relate to the Tygron Engine?
The Tygron Engine consists of two essential components: server software and a client application. When you use the Tygron Engine installer, you actually only install the client application of the Tygron Engine. Clicking buttons to create projects, start session, place buildings, or perform other tasks, actually sends instructions to the server software, where the actual session is (or will be) hosted. The client application then receives data from the server to display to the user, graphically. The API is part of the server software, and allows a user to write their own application to send instructions and/or display data. This means that the API can be used to automate tasks, such as the generation of new projects, or the placement or buildings, and can be used to analyse the data present on the server.
When to use the API?
The API is meant for technical users, with software developers in particular. Since most tasks can be performed using the client application available to all users, this method is preferred for most use-cases, and is made as user-friendly as possible for most users. Tasks for which the API can be used include:
- Automated data analysis, such as building density analysis during a session
- Automated interactions, such as measures activated under specific circumstances
- (Automated) data entry from a database or program into the Tygron Engine, such as possible function types
- Automated data extraction, such as taking the spatial results from a session to use as input for other data analysis programs.
Structure
The API is structured in such a way that from the root url of the API, it is possible to reach all parts of the API, provided you have sufficient credentials. The first section is related to data and operations related to the Tygron Engine itself, such as user and project management. It also provides access to a second section, which relates to specific projects currently running on the server. The credentials strictly required for these sections differ.
Data and Events
Each section offers two types of access: data and events.
Data can be requested, and is returned without operating on it. This is (often static) data which is readily available to the server software.
Events signify some operation, in most cases altering the data, but not necessarily. These can be operations where data is added, updated, or deleted, but may also be required for aggregating certain types of data, such as currently running sessions.
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.
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.
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.
HTML (human readable)
The API can be accessed via the browser. You will be prompted to log in with your Tygron Engine username and password. When using the browser, all content will be returned to you in HTML format, which your browser will be able to display. This means that, 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.
JSON (applications)
When making requests to the API, it is also possible to receive the data in JSON format. This format allows applications to easily process the data. To see a preview of how data will look when requested in JSON format, look for the "Show in JSON format" link on the HTML pages when navigating the API using the browser.
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 the Tygron Engine.
POST requests are used to fire events on the server. In most cases, this means some specific instruction to do something for the server. Examples are starting or creating projects. Some events do not require any additional input. Others require one or more parameters to be provided. When firing an event in the browser, the additional parameters are sent using a form on the page, and an HTML page is returned in response.
The difference between GET and POST requests is not directly apparent when using the browser. When creating or configuring your own application, it is important to take note of the type of request required to request data or perform a task.
HTML response example
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 example
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.
Return codes
When making requests, the http status codes returned can provide insight into whether your request was successful, or why a request has failed.
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 status code 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.
Performing basic tasks
Across the API, most tasks a user may want to perform take a similar form. Requesting data can be done with a GET request. Performing an operation on the server is done with a POST request.
Because the API is subject to change in future releases, and the fact that it is its own (albeit technical) documentation, this article does not provide many specific examples. Instead, the user is encouraged to navigate the API in their browser.
Users and projects
It is possible to request data concerning the current user and the user's domain, in the first section of the API. It is also possible to perform user and project management, depending on the level of your account, by firing the events available at this level.
Sessions
Projects can be created, and started, joined, and stopped as sessions, in the first section of the API. A running session takes up a "slot" on the server. The session then takes its own credentials to access this second part of the API. This credential, a token (as described earlier) can be obtained with an event.
Starting and stopping 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.
Session data and interaction
The second part of the API pertains to data and operations in specific sessions currently running. Data can be requested about all spatial and non-spatial components of a game. It also provides an exhaustive list of all operations you can perform in the session, from pausing and unpausing the game to constructing buildings. If the project was created using real geographical data, the size and coordinates of the map can also be found. Lastly, it provides an interface which, via long-polling, can allow external application to be informed whenever an update of the data takes place.