View source for 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 technical users, as the ability to create or configure your own software is implicitly required.

For the latest updates go to: [[API Changes]].

==How does the API relate to the {{software}}?==
The {{software}} consists of two essential components: server software and a client application. When you use the {{software}} installer, you actually only install the client application of the {{software}}. 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.

The root API for the {{software}} can be reached by appending the URL for the {{software}} with "/api/". For example: {{url|link=true|protocol=true|append=/api/}}

==When to use the API?==
The API is meant for technical users. Specifically, software developers will be able to make the best use of the API. For most users, it is recommended to use the client application. The client application has been made user-friendly, and is the preferred method of interacting with the {{software}} in most use-cases.

There are a number of more technical tasks which do require the API to be used, and which expand the usability of the {{software}} greatly. 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 {{software}}, 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.
<!--* [[indicators#API indicators|API indicators]], which allow showing the results of a complex calculation as an indicator score.-->

==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 {{software}} 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. When accessing the root API via the browser, you will be prompted for these credentials. The {{software}} uses [http://en.wikipedia.org/wiki/Basic_access_authentication Basic access authentication].

====Session Tokens====
The root API requires authentication, but to access a Session ("/api/session/") you need a token. The token is provided when you execute the join session event via the API. It can also be retrieved via the editor interface by selecting Tools-> API Overview.

<pre style="white-space: pre-wrap; 
white-space: -moz-pre-wrap; 
white-space: -pre-wrap; 
white-space: -o-pre-wrap; 
word-wrap: break-word;">Token: 92043566V433Q8UdMO9ThDanINnTNOIX
</pre>

The token serves as an authentication for a specific sessions. Each session has a different token. For convenience in the browser, you can also append a query parameter "token" to your URL, to provide the proper token. For example:

<pre style="white-space: pre-wrap; 
white-space: -moz-pre-wrap; 
white-space: -pre-wrap; 
white-space: -o-pre-wrap; 
word-wrap: break-word;">?token=92043566V433Q8UdMO9ThDanINnTNOIX</pre>

===Navigating the API===
[[File:IOServicesEventsOverview.jpg|thumb|right|300px|The IOServicesEvents page of the API. This overview displays events used to start and manage sessions.]]
For a more specific overview of all 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 "sessions" on the server. When attempting to access a session, you must be sure to provide an appropriate token.

=====HTML (human readable)=====
The API can be accessed via the browser. You will be prompted to log in with your {{software}} 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 {{software}} 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 [https://en.wikipedia.org/wiki/JSON 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 {{software}}.

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=====
<pre style="white-space: pre-wrap; 
white-space: -moz-pre-wrap; 
white-space: -pre-wrap; 
white-space: -o-pre-wrap; 
word-wrap: break-word;">
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&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
</pre>

====JSON response example====
<pre style="white-space: pre-wrap; 
white-space: -moz-pre-wrap; 
white-space: -pre-wrap; 
white-space: -o-pre-wrap; 
word-wrap: break-word;">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","delftshowcase17"]

RESPONSE HEADERS:
HTTP/1.1 200 OK
Content-Type: application/json
Date: Wed, 13 May 2015 09:09:56 GMT
Content-Length: 1
</pre>
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 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 session, until the session is closed. If the project has been opened in Single User or Multi User 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 token 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 running project. It also provides an exhaustive list of all operations you can perform in the session, from pausing and unpausing the session 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 an external application to be informed whenever an update of the data takes place.

====Keeping session active====
The server will automatically close a session which has not been interacted with by a known client for 15 minutes (depending on whether [[keep alive]] is active). An application can should include a client token with all POST requests it makes to indicate that the application is still actively connected and interacting with the session. If it is necessary to keep the session active without affecting it by firing events, it is possible to use the update polling feature, which is also accessed via POST requests. This will only request data from the session without changing it, and will be recognized as an interaction from the application.

==Software Development Kit==
To make working with the API easier, Tygron also offers a Software Development Kit. This is a library which can be used while developing your application, with functionality for creating and maintaining a connection with the {{software}}, parsing data requested via the API, and performing tasks in a similar manner as users do via the Client. The current version of the SDK is available here: [https://engine.tygron.com/api/developer/ SDK]. Note that you need to have active {{software}} login credentials to make us of this SDK.

{{article end
| notes=
* Authentication to the root of the API is based on a username and password. For information on how to authenticate using accounts which have 2-factor authentication enabled, please contact {{support}}.
|seealso=
* [[API tutorial]]
}}