-
Notifications
You must be signed in to change notification settings - Fork 4
API Guidelines
First, reconsider the need for other clocks. The provided clock app:
- runs on any device with a modern web browser.
- has a number of features that are not supported on other clocks.
- has support for the most common FREMO member languages.
If you still want to use other clocks there are a number of options:
- Integrate the other clock by getting time/status from the open API. For example, integrations has already been made with JMRI.
Integrating analogue clocks is possible. These clocks ticks by sending electrical pulses for each minute or second. You have to create a device that polls the API Clock Status each second and check if the clock is running. In order know how much to advance the clock, i.e. how many pulses to generate, you need to compare the time difference between current last poll and last poll. When resetting time when starting a new game, fast pulsing the clock to the start time must be considered.
You fetch the time by repeatedly calling the API with clock name specified. To fetch the time does not require a user name nor a password.
In order to react on clock status changes, for example start/stop, pause, messages etc, it is recommended to fetch the status (time) at maximum two seconds interval. The Clock Client App fetches status with two-second interval, which seems enough to react to changes fast enough.
Any action that modify the clocks state required the clocks administrator password. Some some functions are also permitted using the clocks user password. All calls that requires password returns Unauthorized when no or incorrect password is provided. The clock's administrator password must be set when a new clock instance is created.
The API is English-only. Clients has the responsibility to translate to other languages. The Clock Client App is an example of doing this.
The OPENAPI specification is the most updated documentation. You can also try the API using this page. If the page is not displayed, do a hard request by holding the SHIFT-key when refreshing the page.
The placeholders are the data you replace with your data.
- The {server} placeholder in the url:s represents a name or ip-address with an optional port number, for example 192.168.0.182:5001 or fastclock.azurewebsites.net
- The {clock} placeholder in the url's is the name of the clock instance. If you request a non-existing clock you get Not Found.
- The {userPassword} placeholder you replace with the user- or administrator password.
- The {adminPassword} placeholder you replace with the administrator password.
- The {userOrStationName} placeholder you replace with a suitable name that describes your client user.
- The {reason} placeholder must be one of the predefined values.
Changed from version 2.6.0
The API follows the Open API specifcation. Most development tools support this, which makes it easier to consume ang later update if the API changes. You can retrieve Open API medadata that is a machine readable API specification:
GET https://{server}/openapi/v2/openapi.json
You can also retrieve a documentation page of the API by opening the following link in your browser:
https://{server}/openapi
Go to the cloud version API documentation page.
New from version 2.6.0
At any error, the API returns an error message with a detailed description of what went wrong and some help to solve it.
{
"statusCode": 404,
"documentationLink": "https://github.com/tellurianinteractive/Tellurian.Trains.ModuleMeetingApp/wiki/API-Guidelines",
"messages": [
"Clock demo2 does not exist. ",
"Use '/api/avaliable' to find which clocks that currently exists.",
"See documentation how to create a new clock."
]
}GET https://{server}/api/clocks/available
[
"Demo",
"Custom1",
"Custom2"
]GET https://{server}/api/clocks/{clock}/time
{
"name": "Demo",
"weekday": "Wednesday",
"time": "06:02",
"duration": 15,
"isRunning": false,
"isRealtime": false,
"isCompleted": false,
"message": "",
"speed": 5.5,
"isUnavailable": false,
"realEndTime": "13:14",
"fastEndTime": "21:00",
"isPaused": false,
"pauseTime" : "12:00",
"pauseReason": "Dinner",
"expectedResumeTimeAfterPause": "13:00",
"stoppedByUser": "",
"stoppingReason": "SelectStopReason"
}- weekday - { None | Monday | Tuesday | Wednesday | Thursday | Friday | Saturday | Sunday }
- duration - is total game duration in hours. May have fraction of hours; 15.5 means 15 1/2 hour.
- pauseReason - { None | Breakfast | Lunch | Dinner | Coffe | Meeting | Closing }
- stopReason - see Stop Clock below.
- isUnavailable - this is always false. Clock app should use it internally to signal that API is not available.
- realEndTime - this time includes time for pause if both pauseTime and expectedResumeTimeAfterPause is specified.
PUT https://{server}/api/clocks/{clock}/start?user={userOrStationName}&password={userPassword}
- User- or station name is required when the user that stopped the clock wants to start it again. Should be url-encoded if it contains non-ASCII characterns (like åäø).
- UserPassword is optional but may be required by the administrator. Returns Unauthorised if password is required but no or wrong password is provided or if another user tries to start the clock.
NOTE Only the user that stopped the clock or the administrator can restart the clock.
PUT https://{server}/api/clocks/{clock}/stop?user={userOrStationName}&password={userPassword}&reason={aReason}
- User- or station name should be url-encoded if it contains non-ASCII characterns (like åäø). Returns BadRequest if not provided.
- UserPassword is optional but may be required by the administrator. Returns Unauthorised if password is required but no or wrong password is provided or if another user tries to start the clock.
-
Reason should be one of the strings below. Returns BadRequest if other value is provided.
- StationControl - problems with operating a station.
- PointProblem - problems with one or several points.
- TrackProblem - Problem with track , for example module joints.
- BoosterError - Booster not working or shortcuts that hinders operation.
- LocoNetError - Problems with LocoNet cabling and/or signals.
- CablingError - Other cabling error.
- CentralError - Problems with the digital central(s).
- Delays - Sever delays in operation requires stopping clock to catch up.
- DriverShortage - Duties become unassigned after their start time requires clock to be stopped.
- Derailment - A derailment that take some time to fix.
- Other - Other unspecified reason.
GET https://{server}/api/clocks/{clock}/users?password={adminPassword}
- AdminPassword is required. Only a user with administrator password can see users of the clock. Returns Unauthorised if no or wrong password is provided.
[
{
"ipAddress": "192.168.0.182",
"userName": "Munkeröd",
"lastUsedTime": "2020-06-22 21:25:28"
},
{
"ipAddress": "192.168.0.201",
"userName": "Kalle",
"lastUsedTime": "2020-06-22 21:25:26"
}
]NOTE From Clock App release 2.5.3 this action requires administrator password.
GET https://{server}/api/clocks/{clock}/settings?password={adminPassword}
{
"name": "Demo",
"shouldRestart": false,
"isElapsed": false,
"isRunning": false,
"startWeekday": "0",
"startTime": "06:00",
"speed": 5.5,
"durationHours": 15,
"pauseTime": "",
"pauseReason": "0",
"expectedResumeTime": "",
"showRealTimeWhenPaused": false,
"overriddenElapsedTime": "",
"message": "",
"mode": "0",
"password": "password"
}NOTE: Changed to PUT from version 3.0.0.
PUT https://{server}/api/clocks/{clock}/Update?user={userOrStationName}&password={adminPassword}
- User- or station name is required. Should be url-encoded if it contains non-ASCII characterns (like åäø).
- AdminPassword is required. Only a user with administrator password can update the clock settings. Returns Unauthorised if no or wrong password is provided.
Payload in post is same as in Get clock settings.
NOTE: New way to create new clock from version 3.0.0. Old way will return Not Found.
POST https://{server}/api/clocks/create?user={userOrStationName}
Payload in post is same as in Get clock settings. Creates a new clock instance with the name given in provided settings. In this request you can set the administrator- and user password in settings. You must remember the administrator password in order to change the clock settings later.
© Tellurian Interactive AB - 2018-2024