Database plugin REST API

This document summarises the RESTful API to the Polaric-aprsd backend server, provided by the database plugin. This is used by clients running in standard web-browsers.

The URL identifies the resource (or service) to be invoked. For REST APIs, the URL identifies the resource and the operation to be performed on it is determined by the HTTP method: GET (read object), PUT (update), POST (add, post), DELETE (remove it). Where a representation of the state is required or returned, the JSON format is used. Some operations that perform search expect query parameters.

Most services will require authorization: O=open, L=login, S=SAR, A=admin.

See more info on Client Authentication. To access ‘L’, ‘S’ or ‘A’ services, requests must be authenticated. To access ‘O’ services, we do not use authentication.

Trackers API

Source: TrackerApi.java

/trackers

GET

L

Get ‘my trackers’ for user.

POST

L

Add a tracker (for logged-in user)

/trackers/{id}

DELETE

L

Delete a tracker for the logged in user

PUT

L

Update a tracker (for logged in user)

/trackers/tags

GET

L

Get tracker tags for the logged in user

POST

L

Add a tag to the logged in user’s trackers

/trackers/tags/{id}

DELETE

L

Delete a tag for the logged in user
GET /trackers

Returns a list of tracker objects owned by user or by the user given as request parameter ‘user’.

Form Parameters:

  • user – (optional) Userid of user to get trackers for. If not given, use the identity of user that performs the request.

Status Codes:
Response JSON Object:

  • id (string) – The callsign of the tracker

  • user (string) – Userid of the owner

  • alias (string) – Alias to be used when active. Null if not set

  • icon (string) – Icon to be used when active. Null if not set

  • active (boolean) – True if active and visible

  • lastHrd (date) – When it was last heard

POST /trackers

Add a tracker to the list of tracker objects owned by user.

Form Parameters:

  • user – (optional) Userid of user to get trackers for. If not given, use the identity of user that performs the request.

Status Codes:
Request JSON Object:

  • id (string) – The callsign of the tracker

  • user (string) – Userid of the owner

  • alias (string) – Alias to be used when active. Null if not set

  • icon (string) – Icon to be used when active. Null if not set

  • active (boolean) – True if active and visible

  • lastHrd (date) – When it was last heard

DELETE /trackers/(id)

Remove a tracker from user’s list

Parameters:

  • id (string) – Callsign/ident of the tracker

Status Codes:
PUT /trackers/(id)

Update a tracker

Status Codes:
Request JSON Object:

  • id (string) – The callsign of the tracker

  • user (string) – Userid of the owner

  • alias (string) – Alias to be used when active. Null if not set

  • icon (string) – Icon to be used when active. Null if not set

  • active (boolean) – True if active and visible

  • lastHrd (date) – When it was last heard

GET /trackers/tags

Returns a list of tracker tags. Tags will be applied to all trackers owned by user.

Status Codes:
Response JSON Array of Objects:

  • tag (string) – Tag

POST /trackers/tags

Add tags to be applied to trackers owned by user.

Status Codes:
Request JSON Array of Objects:

  • tag (string) – Tag

Signs API

Source: SignsApi.java

/signs

GET

L

Get all signs

POST

L

Add a sign

/signs/{id}

GET

L

Get a specific sign

PUT

L

Update a sign

DELETE

L

Remove a sign

/signs/types

GET

O

Get a list of types (categories)
GET /signs

Returns a list of sign objects

Status Codes:
Response JSON Array of Objects:

  • id (string) – Unique id for sign

  • url (string) – Link to a web-page or image

  • descr (string) – Description

  • icon (string) – Filename of icon

  • scale (long) – Scale of map from which sign is to be visible

  • type (int) – Category of sign

  • tname (string) – Type name

  • pos (double[]) – Position of sign (longitude, latitude)

POST /signs

Add a sign

Status Codes:
Request JSON Object:

  • id (string) – Unique id for sign

  • url (string) – Link to a web-page or image

  • descr (string) – Description

  • icon (string) – Filename of icon

  • scale (long) – Scale of map from which sign is to be visible

  • type (int) – Category of sign

  • tname (string) – Type name

  • pos (double[]) – Position of sign (longitude, latitude)

GET /signs/(id)

Returns a given sign objects

Parameters:

  • id (string) – Unique dent of the sign

Status Codes:
Response JSON Object:

  • id (string) – Unique id for sign

  • url (string) – Link to a web-page or image

  • descr (string) – Description

  • icon (string) – Filename of icon

  • scale (long) – Scale of map from which sign is to be visible

  • type (int) – Category of sign

  • tname (string) – Type name

  • pos (double[]) – Position of sign (longitude, latitude)

PUT /signs/(id)

Update a given sign object

Parameters:

  • id (string) – Unique ident of the sign

Status Codes:
Request JSON Object:

  • id (string) – Unique id for sign (will be ignored)

  • url (string) – Link to a web-page or image

  • descr (string) – Description

  • icon (string) – Filename of icon

  • scale (long) – Scale of map from which sign is to be visible

  • type (int) – Category of sign

  • tname (string) – Type name

  • pos (double[]) – Position of sign (longitude, latitude)

DELETE /signs/(id)

Remove a given sign objects if it exists

Parameters:

  • id (string) – Unique ident of the sign

Status Codes:
GET /signs/types

Returns a list of valid categories for signs

Status Codes:
Response JSON Array of Objects:

  • id (int) – Unique numerical id

  • name (string) – Descriptive name of category

  • icon (string) – Filename of icon

Historical search API

Source: HistApi.java

/hist/{id}/aprs

GET

O

Get APRS raw packets for a given callsign

/hist/{id}/trail

GET

L

Get historical trail for a given callsign

/hist/{id}/hrdvia

GET

O

Get points heard via a callsign

/hist/snapshot/{x1}/{x2}/{x3]/{x4}

GET

L

Get snapshot (area, time)
GET /hist/(id)/aprs

Returns a list of received APRS packets for a given callsign. Timespan can be given.

Parameters:

  • id (string) – APRS callsign

Form Parameters:

  • n – Max number of packets to be returned

  • tto – (optional) End of timespan to search (if not given or “-/-” it means now) [1]

  • tfrom – (optional) Start of timespan to search [1]

Status Codes:
Response JSON Array of Objects:

  • time (Date) – Timestamp for packet or when received

  • source (string) – Source channel

  • from (string) – Sender callsign

  • from – Destination callsign (e.g. “APRS”)

  • via (string) – Digipeater/igate path

  • report (string) – The APRS report (content of packet)

GET /hist/(id)/trail

Returns a trail a list of positions for a given callsign. Timespan must be given. It returns a JsOverlay JSON object to be presented as a overlay on the map.

Parameters:

  • id (string) – APRS callsign

Form Parameters:

  • n – Max number of points to be returned

  • tto – (optional) End of timespan to search (if not given or “-/-” it means now) [1]

  • tfrom – (optional) Start of timespan to search [1]

Status Codes:
GET /hist/(id)/hrdvia

Returns a list of positions from where traffic have been received by the callsign. Timespan must be given. It returns a JsOverlay point-cloud JSON object to be presented as a overlay on the map.

Parameters:

  • id (string) – APRS callsign

Form Parameters:

  • n – Max number of points to be returned

  • tto – (optional) End of timespan to search (if not given or “-/-” it means now) [1]

  • tfrom – (optional) Start of timespan to search [1]

Status Codes:
GET /hist/snapshot/(x1)/(x2)/(x3)/(x4)

Returns a list of positions, trails, etc. in a given geographical area at a given time instant. It returns a JsOverlay to be presented as a overlay on the map. The choice of colours for the trails is remembered between calls from the same user and can be reset.

Parameters:

  • x1 (double) – West latitude limit (left of the map)

  • x2 (double) – East latitude limit (right of the map)

  • x3 (double) – South longitude limit (bottom of the map)

  • x4 (double) – North longitude limit (top of the map)

Form Parameters:

  • tto – Date and time [1]

  • filter – View filter to be applied

  • reset – Reset colours used for the trails

Status Codes:

Json Object API

Source: RestApi.java

The server does not interpret the content of raw objects (encoded in JSON). Clients may use this API to store different things. Tags can be used to give info what the objects contain.

/objects/{tag}

GET

L

Get a list of objects for the logged in user

POST

L

Add a (raw text) object for the logged in user

/objects/{tag}/{id}

GET

L

Get a single (raw text) object

PUT

L

Update a (raw text) object

DELETE

L

Remove an object

/objects/{tag}/{id}/share

GET

L

Get users with which the object is shared

POST

L

Add a sharing of the object

DELETE

L

Remove a sharing of the object
GET /objects/(tag)

Returns a list of objects with the given tag and for the logged in user.

Parameters:

  • tag (string) – Tag that denotes a type or category of object

Status Codes:
Response JSON Array of Objects:

  • id (string) – Ident of the object

  • readOnly (boolean) – Object should be treated as read-only

  • noRemove (boolean) – Object shouldn’t be removed…

  • data (string) – Object in raw JSON (or XML)

POST /objects/(tag)

Add a object with the given tag and for the logged in user. The request body should contain a raw text representation of the object to be added. It is not parsed, but will in most cases be in JSON format. Returns the numeric identifier of the newly posted object.

Parameters:

  • tag (string) – Tag that denotes a type or category of object

Status Codes:
GET /objects/(tag)/(id)

Get a single object having the given id and tag. A raw text is returned (in most cases in JSON format)

Parameters:

  • tag (string) – Tag that denotes a type or category of object

  • id (int) – Numeric identifier for object

Status Codes:
PUT /objects/(tag)/(id)

Update a single object having the given id and tag. The request body should contain a raw text representation of the object to be added. It is not parsed, but will in most cases be in JSON format.

Parameters:

  • tag (string) – Tag that denotes a type or category of object

  • id (int) – Numeric identifier for object

Status Codes:
DELETE /objects/(tag)/(id)

Remove a single object having the given id and tag (if it exists).

Parameters:

  • tag (string) – Tag that denotes a type or category of object

  • id (int) – Numeric identifier for object

Status Codes:
GET /objects/(tag)/(id)/share

Get a list of users (or groups) with which the given object is shared

Parameters:

  • tag (string) – Tag that denotes a type or category of object

  • id (int) – Numeric identifier for object

Status Codes:
Response JSON Array of Objects:

  • id (string) – Ident of the user

  • readOnly (boolean) – User has read-only access

POST /objects/(tag)/(id)/share

Add a user (or group) with which the given object is shared.

Parameters:

  • tag (string) – Tag that denotes a type or category of object

  • id (int) – Numeric identifier for object

Status Codes:
Request JSON Array of Objects:

  • id (string) – Ident of the user

  • readOnly (boolean) – User has read-only access

DELETE /objects/(tag)/(id)/share/(userid)

Remove a sharing with a user for the given object (unlink)

Parameters:

  • tag (string) – Tag that denotes a type or category of object

  • id (int) – Numeric identifier for object

Status Codes: