REST API
In Q2 2015 you can connect to the Tygron Engine via a REST API.
More info about rest can be found here
Specs
- JSON format.
- SSL encrypted with same credentials for normal Engine login.
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.
The api for the Tygron Engine can be reached by appending the URL for the Tygron Engine with "/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.
When you wish to interact with a specific project currently active on the server, you will need to provide the appropriate server token for the session. To obtain such a token, you can trigger the JOIN_SESSION event. Part of the information returned includes a ServerToken. This token can be used to access a session by adding it to the header of your http request (i.e. serverToken: X). For convenience in the browser, you can also append "?token=X" to your URL.
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.
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.