Everything you could possibly ask for, and more

RESTful API

Users

GET /users/
Return a list of users.
Admin privileges are required.
If the session provided is not associated with an admin account, the result returned is the the same as the one of /users/UId, UId being the UId associated with the provided session.

Parameters Description
pretty if true, return a reader-friendly JSON result
details if true, return first and last name, along with UId and username
session a valid session

POST /users/
Create a new account.
No particular privileges are required. (In order to prevent bots from mass registering, accounts can only be registered once per hour per IP address)*.

Parameters Description
pretty if true, return a reader-friendly JSON result
username the username for the new account (needs to be unique)
password a password**
first first name
last last name
email a valid email address
  • no limit is available as of now, since multiple users are registered when testing. ** any check on the strength or correctness of the password should be performed on the client side.

GET /users/UId
Return information about a given user.
Such information is only returned if the provided session matches a valid session for the requested user (or the session is that of an admin).

Parameters Description
pretty if true, return a reader-friendly JSON result
session a valid session for the user UId (or an admin session)

PUT /users/UId
Update information about an user. Updating is only allowed if the provided session matches one of the sessions for the user to be updated (or that of an admin).
For security reasons, the current password is required when updating the username and/or the password (unless the provided session is that of an admin).

Parameters Description
pretty if true, return a reader-friendly JSON result
session a valid session for the user to be updated (or an admin session)
username the new username
password the new password
current the current password
first the new first name
last the new last name
email the new email address

DELETE /users/UId
Delete all the information about a user (which includes information about antennas and locations).
A valid session for the requested user is mandatory, along with the current password (or an admin session, without any password).

Parameters Description
pretty if true, return a reader-friendly JSON result
session a valid session for the user to be deleted (or an admin session)
current the current password

Antennas

GET /antennas/
Return a list of the antennas paired to a given user.
A valid session is required.

Parameters Description
pretty if true, return a reader-friendly JSON result
session a valid session

POST /antennas/
Pair a new antenna to an user.
Antennas are uniquely identified by their MAC address: each antenna can only be paired to one account at a time. If you are trying to pair an antenna that was previously owned by somebody else, the previous owner needs to delete the antenna from its account.

Parameters Description
pretty if true, return a reader-friendly JSON result
session a valid session
identifier the unique identifier for the antenna
name a human-friendly name

GET /antennas/AId
Return information about a single antenna.
The requested antenna has to be paired to the requesting user, or the requesting user should be an admin.
If /antennas/all/UId is requested by an administrator, a list of all of the antennas paired to the user UId is returned.

Parameters Description
pretty if true, return a reader-friendly JSON result
session a valid session

PUT /antennas/AId
Update the information regarding a single antenna.
Only the name can be updated. If you need to update the MAC address, you need to delete the antenna first, and create a new one.
Users can only update antennas paired to their account.

Parameters Description
pretty if true, return a reader-friendly JSON result
session a valid session
name a human-friendly name

DELETE /antennas/AId
Delete the specified antenna.
For security reasons, the password is required along with a valid session.

Parameters Description
pretty if true, return a reader-friendly JSON result
session a valid session
password the current password

Hotspots

GET /hotspots/
Return information about the hotspots.

Parameters Description
pretty if true, return a reader-friendly JSON result

POST /hotspots/TId
Add a new hotspot.
Hotspots can only be added by an admin.
Each hotspot is uniquely identified by its MAC address. When a new hotspot is added, a secret key needs to be specified. This secret key will be used by the hotspot, along with its MAC address, when using the API.

Parameters Description
pretty if true, return a reader-friendly JSON result
session a valid admin session
name a unique, human-friendly name
secretkey a secret key, or password, that will be used by the hotspot
latitude latitude of the new hotspot
longitude longitude of the new hotspot

PUT /hotspots/TId
Update an hotspot.
Hotspots can only be updated by an admin.
Only the hotspot’s name and secret key can be updated. In order to change the MAC address, the hotspot needs to be deleted and, then, added once again.

Parameters Description
pretty if true, return a reader-friendly JSON result
session a valid admin session
name a human-friendly name
secretkey the new secret key
latitude new latitude of the hotspot
longitude new longitude of the hotspot

DELETE /hotspot/TId
Delete an hotspot.
For security reasons, the password is required along with a valid session.

Parameters Description
pretty if true, return a reader-friendly JSON result
session a valid admin session
password the current password

Location

GET /location/AId
Provide a list of the latest locations recorded for a given antenna.
The locations are indirectly returned by providing a list of the hotspots that recorded the antenna’s presence.

Parameters Description
pretty if true, return a reader-friendly JSON result
session a valid session
from the number of the first record that should be returned
limit the number of records to be returned (must be <= 50)

POST /location/
Submit information about the antennas located by an hotspot.
Multiple antennas can be submitted with a single request.

Parameters Description
pretty if true, return a reader-friendly JSON result
name the unique identifier/name of the hotspot
secretkey the secret key for the hotspot
antennas a base64 encoded string containing a JSON-compliant array of MAC addresses and RSSI’s*
  • ‘antennas’ should be the base64 encoding of a JSON array following this structure: [{"MAC":"00:01:02:03:04:05","RSSI":-1},{"MAC":"...","RSSI":-2},...]

Sessions

POST /sessions/
Request a new session.
For the session to be created, the username and password of a valid account are to be provided.
The Unix timestamp of the expiration date may be provided. If not, the default value is timestamp + 3600.

Parameters Description
pretty if true, return a reader-friendly JSON result
username a valid username
password the password for the provided username
expiration a Unix timestamp of the expiration date