Web API¶
The web API is consumed by the Sulu CMS frontend and by public mobile apps. It uses the same prefix as the
REST API plus /web
, therefore the standard prefix normally is /api/web
. All endpoints below
must be prefixed with this and your domain name.
https://tag.example.com/api/web
Web API vs REST API¶
- Authentication and Privileges
The REST API is available for high privilege devices, the apps consuming it are issued dedicated credentials that can be revoked at any time, their source code is not public and no build is released to the public.
The Web API is available for public apps and the mobile site, it uses a loose authentication based on a unique code assigned to each delegate and allows changes only to the owner’s record. Some of its method might also implement rate limiting or throttling to prevent abuse.
- Time Travel
- Time travel is not allowed for the Web API, sending a “recordedAt” timestamp against an interaction is forbidden, such value is always set to the current timestamp.
- State
- The state of a delegate is always calculated server-side, this is to prevent duplication of the logic on both server and client. A client is free to perform additional checks, but in case of a conflict the server state should prevail.
- Session
- Another big difference is that the Web API is stateful or stateful-like, and implements security measures to prevent XSS and CSRF attacks. These measures are based on the session kept through HTTP Cookie for Angular/React apps.
GET /delegate/myself¶
Returns the current delegate state. While the UI state is stored only in the client local storage, the data state is always computer server side, the client might guess it and keep track of it locally to improve performance but should always rely on the server version if local and remote state don’t match. Fear not, every request meant to have an effect on the state will return the updated state, so you probably need to call this just once and react to you own actions according to what the state has become.
The state includes all delegate information, including delegate connections, joined devices and check-ins. See the example below:
{
"delegate": {
"data": [],
"barcode": "0123456789",
"id": 4,
"email": "giovanni@satellite.co.nz",
"sources": [
"admin"
],
"createdAt": "2017-10-09T14:32:14+13:00",
"updatedAt": "2017-10-10T14:42:39+13:00"
},
"unlockDelegates": [],
"relations": {
"join": {
"4-1-0": {
"recordedAt": 1507520650,
"delegate_id": 4,
"device_id": 1
}
},
"checkIn": {
"4-1-0": {
"recordedAt": 1507520624,
"delegate_id": 4,
"device_id": 1
}
},
"connect": {
"4-1-4": {
"recordedAt": 1507590718,
"delegate_id": 4,
"device_id": 1,
"targetDelegate_id": 4
}
},
"connected": {
"4-1-4": {
"recordedAt": 1507590693,
"delegate_id": 4,
"device_id": 1,
"targetDelegate_id": 4
}
},
"booking": {
"4-2-0": {
"recordedAt": 1507599562,
"delegate_id": 4,
"device_id": 2
}
},
"invite": {
"4-2-6": {
"recordedAt": 1507599627,
"delegate_id": 4,
"device_id": 2,
"targetDelegate_id": 6
},
"4-2-5": {
"recordedAt": 1507599734,
"delegate_id": 4,
"device_id": 2,
"targetDelegate_id": 5
}
},
"notifyInvitees": {
"4-2-0": {
"recordedAt": 1507599759,
"delegate_id": 4,
"device_id": 2
}
}
}
}
Note
This is fundamentally different from the REST GET /delegate/{idType}:{id} in that this processes all delegate data and history to provide a snapshot of the current state. Also this might contain session derived information.
Another difference is that your current state is cached for a while, until it gets flagged as stale or an action clears it.
GET /delegate/list¶
Returns all visible delegates and their public details. Depending on your current data state, in particular your connections you might see more details against delegates that have accepted to connect with you.
[
{
"id": 4,
"firstName": "Giovanni",
"lastName": "Gioffreda",
"email": "giovanni@satellite.co.nz"
},
{
"id": 5,
"firstName": "John",
"lastName": "Doe"
},
{
"id": 6,
"firstName": "Jane",
"lastName": "Doe"
},
{
"id": 14,
"firstName": "Walter",
"lastName": "White"
},
{
"id": 20,
"firstName": "Barry",
"lastName": "Smith"
}
]
Note
See Web API vs REST API.
GET /device/list¶
Return all visible devices and their public details. Depending on your current data state, in particular your joins and check-ins you might see more details against devices you’ve interacted with.
By default this method returns only sessions, if you are looking for another device type you can specify the type you want in your query (the first two calls are equivalent):
/device/list
/device/list?type=session
/device/list?type=room
/device/list?type=bookable
A comprehensive list of device types is:
- room
- The rooms/areas of an event. Usually sessions are located into a room, assigned to them as their parent device.
- session
- A session, usually has a time frame (startAt and endAt), a name and a description. Delegates check-in into them and sometimes join them to express their interest.
- sponsor
- A sponsor, like the name suggests, is a third party attending the event and showcasing something.
- rfidreader
- Digital devices able to read/write radio devices in a certain range (like UHF readers).
- regoapp, mobileapp
- Physical devices running a Satellite Tag app (registration, gate app, sponsor app, …).
- bookable
- Is a generic devices that can be used as a target for custom booking logic.
Below is a response:
[
{
"id": 2,
"name": "Meeting Table 1",
"code": "mt1",
"startAt": 1507662000,
"endAt": 1507698000
},
{
"id": 3,
"name": "Meeting Table 2",
"code": "mt2",
"startAt": 1507662000,
"endAt": 1507698000
}
]
Note
See Web API vs REST API.
POST /device-interaction/log¶
Posts a device interaction. Returns the current state as per GET /delegate/myself.
Below you find some sample requests
// posting a check-in to session with ID 2
{
"device_id": 2,
"interactionType": "check-in"
}
// joining the session with ID 2
{
"device_id": 2,
"interactionType": "join"
}
// booking meeting table with ID 3
{
"device_id": 3,
"interactionType": "book"
}
// invite delegate ID 14 to the booked meeting table with ID 3
{
"device_id": 3,
"interactionType": "invite",
"targetDelegate_id": 14
}
A non exhaustive list of the standard interactions is:
- check-in
- Indicates someone has checked in into a session or interacted with any device. It’s the most common action you can use anywhere you don’t need to define custom behaviour or attach complex data to it.
- check-out
- The opposite of a check-in, when someone leaves a session. Currently used to enable “single-entry” sessions.
- join
- Usually referred to a session, it’s a broad term and generally means that delegate is supposed to show up at a particular session or that they are allowed into such session.
- connect
- Indicates the intent of a delegate to connect with another delegate. Depending on the instance a single connect could trigger a connected event (see below) but usually for such event to trigger both delegates need to connect with each other first.
- connected [1]
- This is usually a system generated interaction that triggers when two delegates connect with each other.
- booking, cancel-booking
- These events allow you to book devices. The device you can book should be of a bookable type but this is not enforced. This has been used only for the meeting tables feature so far.
- invite, uninvite, notify-invitees
- These actions are used to invite delegates to a session and/or to notify them. This most likely requires some custom logic that can be added to the AppBundle.
- seen
- This is used only by UHF readers.
- entered, exited [1]
- This allow to detect how many delegates are in a particular area at an event.
Most interaction types we’ve used so far are summarised below:
Interaction | [2] | Description |
---|---|---|
check-in | R M S | A delegate shows up (physically) to an event or session |
check-out | M S | A delegate leaves an event or session |
join | R M S | A delegate is allowed to, has booked or is assigned to an event, session, … |
seen | U | A delegate has been seen at an event or session (usually by a UHF reader) |
entered | U | A delegate has entered an area (usually based on where they’ve been seen) |
exited | U | A delegate has left an area (usually based on where they’ve been seen) |
connect | S | A delegate sends a connection request |
connected | S | A delegate has connected with someone (usually when both reciprocally connect) |
booking | S | A delegate has booked something like a meeting, session, … |
cancel-booking | S | A delegate has cancelled a booking |
invite | S | A delegate has invited someone to something |
uninvite | S | A delegate has uninvited someone he previously invited |
notify-invitee | S | A delegate asks to notify an invitee about something |
order | M S | A delegate orders something, usually a drink |
order-processing | S | A delegate’s order is being processed |
order-cleared | S | A delegate’s order has been completed (usually this fires a text message) |
download | M S | A delegate requests to download something |
downloaded | M S | A delegate has downloaded something |
upload | M | A delegate uploads something |
feedback | S | A delegate sends their feedback |
competition | S | A delegate enters a competition |
voucher | S | A delegate consumes a voucher |
question | S | A delegate asks a question |
lead | M | A delegate records a lead |
poll-vote | S | A delegate votes in a poll |
own | M S | A delegate owns a device (usually for sponsors, to identify staff members) |
R | A delegate’s badge has been printed (usually from the registration app) |
[1] | (1, 2) You should never have to log such interaction, depending on the configuration for your particular instance of Satellite Tag the system will automatically log this events. |
[2] | R: Registration app, M: Mobile app, S: Mobi site/Exhibitor portal, U: UHF readers |
POST /lead¶
Posts a lead. Returns the current state as per GET /delegate/myself.