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 |
| 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 |
| 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 |