5.0 KiB
Tracking App API v1 Draft
General
This is a design for the REST API to be used by the iOS and Android tracking apps.
Event Data
Path
http://sapsailing.com/b964b0
A shortened URL is used. This URL is embedded in the QR code. In case a user does not have a QR code, she can manually enter the URL into the app.
Note that a unique URL needs to be defined per competitor and event.
Verb
GET
Response
{
"serverUrl" : "http://ec2-54-171-89-140.eu-west-1.compute.amazonaws.com:8888"
"event" : {
"eventId" : "123",
"eventTitle" : "Kieler Woche",
"eventStartDate" : 1414414481000,
"eventEndDate" : 1414609200000,
"eventDays": [
{
"eventDayStart" : "1414414481000",
"eventDayEnd" : "1414436081000"
},
{
"eventDayStart" : "1414497600000",
"eventDayEnd" : "1414522800000"
},
{
"eventDayStart" : "1414584000000",
"eventDayEnd" : "1414609200000"
},
]
}
"competitor" : {
"competitorId" : "250cf8b51c773f3f8dc8b4be867a9a02",
"competitorName" : "Alster Segel Club",
"competitorProfileImageUrl" : "http://s3.amazonaws.com/sapsailing/profile_images/68053af2923e00204c3ca7c6a3150cf7.jpeg"
}
}
serverUrl This is the endpoint to be used for all following REST requests.
eventDays An event can be held for several days. This array contains all start and end times of an event day. This is used to remind a user to turn tracking on or off (in order to save battery).
Push Notifications
Event data can be updated via push notifications. These are limited on iOS to 256 bytes (not characters). For this reason, on receiving a push notification, the app must GET the event data.
Check-In
After the user has received the event data with the short URL, the smartphone is mapped to a competitor.
Question: What should be done if a second device is mapped to competitor?
Path
/event/{event_id}/competitor/{competitor_id}/device
Verb
POST
Request
{
"deviceUdid" : "202cb962ac59075b964b07152d234b70",
"deviceType" : "ios",
"pushDeviceId" : "0f744707bebcf74f9b7c25d48e3358945f6aa01da5ddb387462c7eaf61bbad78"
}
deviceUdid A UDID generated by device, generated on first run.
deviceType Either android or ios. Needed for selecting correct push notification service.
pushDeviceId On Android the GCM regId, on iOS the APNS push token. This is needed for sending push notifications to the device.
Upload Profile Image
An image can be uploaded per competitor and event.
Path
/event/{event_id}/competitor/{competitor_id}/profile_image
Verb
POST
Request
Multipart upload with part image containing JPEG image 80%, max dimension 1200px.
Response
{
"profileImageUrl" : "http://s3.amazonaws.com/sapsailing/profile_images/68053af2923e00204c3ca7c6a3150cf7.jpeg"
}
profileImageUrl URL of uploaded image.
Tracking Status
As general information, the tracking status of the smartphone is sent.
Path
/event/{event_id}/competitor/{competitor_id}/tracking_status
Verb
POST
Request
{
"timeStamp" : "14144158370000",
"status" : "start"
}
status Either start or stop.
Send Location
The main data sent by the app.
Path
/event/{event_id}/competitor/{competitor_id}/location
Verb
POST
Request
{
"timestamp" : "14144160080000",
"latitude" : "54.325246",
"longitude" : "10.148556",
"speed" : "3.61",
"course" : "258.11",
}
speed Speed over ground in meters per second.
course Heading in degrees.
Web Sockets
Note that locations should be sent via web socket instead of HTTP POST in order to speed up communication. POST requests can be used as a fallback in case web sockets aren't available.
Bulk Upload Locations
Locations should be sent live during an event. In case of missing network, locations are stored to the device and uploaded to the server later for analysis.
As this could be a lot of data, GZIP compression is a must. Bulk uploads should be chunked, e.g. per day or per 1,000 locations.
Path
/event/{event_id}/competitor/{competitor_id}/location_bulk
Verb
POST
Request
{
"locations" : [
{
"timestamp" : "14144160080000",
"latitude" : "54.325246",
"longitude" : "10.148556",
"speed" : "3.61",
"course" : "258.11",
},
{
"timestamp" : "14144168490000",
"latitude" : "55.12456",
"longitude" : "8.03456",
"speed" : "5.1",
"course" : "14.2",
},
...
]
}