/alerts/
Alerts represent updates in the behaviour or state of certain resources that require attention from fleet operators. Different users may be interested in different alerts and their circumstances. An example would be when a bicycle leaves a service area, it may be appropriate to notify fleet operators of this.
This endpoint implements both a pull HTTP and a webhook-based push model. The latter is for allowing you to take action when new alerts are generated.
Alert Model
This model contains the following properties:
| Property | Description |
|---|---|
| uuid | Unique identifier of the alert. |
| created | Date of creation of the alert. |
| modified | Last date of modification for the alert. |
| roles | Roles that this alert is visible to. Examples are fleet_operator, renteror admin. |
| user | Reference to the user that this alert is related to, if any. |
| causality | Reference to the resource that caused this alert. For example, https://api.noa.one/bicycles/1c12b52b-3f63-499f-a4f3-4a77cab5a737/. |
| alert_type | Type of alert according to acceptable values. |
| message | Default message for that alert. |
| extra | Additional fields with unstructured information associated to the alert. The content of this field is meant to change over time. Make sure to check for existence before accessing specific properties. See more. |
| bicycle | Reference to the bicycle associated with this alert. |
| organization | Reference to the organization that this alert belongs to. |
| url | Link to this entity. |
| state | State of the alert. See more. |
GET Fetch Alerts
This a sample request to retrieve the first page of a list of active alerts for a specific bicycle, sorted by date created in descending order:
GET /alerts/?ordering=-created&bicycle=<bounding-box-coords>&state=new
Authorization: JWT <token>
Accept: application/json;version=1.0
The list of allowed parameters is as follows:
| Parameter | Description |
|---|---|
| page | Number of the page to fetch. |
| organization | Organization that the alerts belong to. |
| state | Desired states for the alerts to be fetched. |
| alert_type | Specific alert type(s) to filter for. |
| bicycle | Constrain the response to only contain alerts for a specific bicycle. |
| ordering | Field used to sort the response. Prepend a minus sign (-) to return in descending order. |
The response contains a list of alerts:
[{
"roles": [ "fleet_operator" ],
"user": null,
"causality": "https://api.lock8.me/api/bicycles/5c15b52b-3f63-499f-a2f3-4a77cfb3a331/",
"alert_type": "bicycle.ride_outside",
"message": "Causality: bicycle 5c15b52b-3f63-499f-a2f3-4a77cfb3a331 | Type: bicycle.ride_outside",
"extra": {
"location": {
"type": "Point",
"coordinates": [
-122.024773,
37.40863
]
},
"bicycle_uuid": "5c15b52b-3f63-499f-a2f3-4a77cfb3a331",
"lock_uuid": "3b12a87f-d30c-46d9-8186-5966ec7b6d13",
"state_of_charge": 48.08984375,
"bicycle_name": "Fast Bicycle",
"lock_bleid": "secure_lock"
},
"bicycle": "https://api.lock8.me/api/bicycles/5c15b52b-3f63-499f-a2f3-4a77cfb3a331/",
"organization": "https://api.lock8.me/api/organizations/81d12b17-628a-425d-8070-4898f4d305ba/",
"uuid": "1bb702bf-b6e2-4813-9024-a86f42cde3e5",
"url": "https://api.lock8.me/api/alerts/1bb702bf-b6e2-4813-9024-a86f42cde3e5/",
"created": "2017-04-23T23:46:26Z",
"modified": "2017-04-23T23:46:26Z",
"state": "new",
},]
Extra Field
This field contains unstructured information associated to the alert. The content of this field varies depending on the nature of the alert and is meant to change over time. Make sure to check for existence before accessing specific properties.
Content Based on Causality
Currently, this field can take two different shapes, depending on the causality bound to the alert:
Bicycle
This extra field contains properties including bicycle_name and bicycle_uuid.
Lock
This extra field contains properties for lock_uuid and lock_bleid.
Common Properties
Regardless of the causality, the extra field can also contain the following properties.
| Property | Description |
|---|---|
| location | Includes the location of the causality in GeoJSON format, if applicable. For example: { "type": "Point", "coordinates": [ -122.024773, 37.40863 ] } |
| state_of_charge | State of charge of the bicycle associated to the alert, if it exists. |
Alert Types
There are various types of alerts that describe different events. The current types of alerts are:
lock.bat.low:bicycle.ride_outside:lock.no_tracking:bicycle.return_outside:bicycle.lost_reported:bicycle.outside_operational_period:bicycle.too_long_idle:lock.shutdown:
Alert States
The alert entity has states and transitions associated to it. The possibles states are:
new: Initial state.resolved: The alert is not a cause for concern anymore. This state can only be reached manually, via the FMS.escalated: This alert was turned into a task or action item.stopped: The condition that generated the alert got resolved, and thus this alert does not apply anymore. This state can only be reached automatically.silenced: The alert is still active but is not visible anymore. This state can only be reached manually, via the FMS.