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)
print	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.