New kid under the block - Dataedpool. Packed in another service or console app, aptly named Quark.Datapool. To describe in clear terms what it really should be is a kind of task that no man has succeeded so far, so we will for sure not try to do so, at least not for now.

For the sake of description, we will use “external actor” or “actor” as a term describing every external user of this fantastic app, and therefore we can broadly describe datapool as a system for disseminating of incident reports to actors and allowing those actors to inform other users about changes relating those incident reports.

Now what?

Actors

Each actor is identified by API key, and may have (or have not) permissions for specific operations. API key is sent as “Authorization” header of each http request requiring authorization:

“Authorization”: “APIKey ”

Actor notifications

Notifications to actors are implemented as webhooks: every actor interested in listening to notifications must provide URL that incident reports should be delivered to as (more or less) standard Common Alerting Protocol messages.

In order to receive notifications, actors must subscribe to a specific notification. Subscriptions are made by executing HTTP requests, allowing finer selection of notifications to receive. Additional status update actions are also done using HTTP requests.

Get available notifications

GET request at /api/webhooks/filters endpoint should retrieve list of all avaiable notifications. This method is available to anonymous users also.

Example:

curl -X GET .../api/webhooks/filters

Response:

[
    {
        "Name": "*",
        "Description": "Listen in on all events."
    },
    {
        "Name": "ticket:address_update",
        "Description": "Ticket address update"
    }
]

Value Name is required for notification subscription.

Value Description
ticket:address_update Notification for incident report update
* All notifications :)

Subscribe to notification

POST request to api/webhooks/registrations is used for subscribing to notifications. This endpoint is accesible only to authorized actors, information

Example:

curl -X POST \
  .../api/webhooks/registrations \
  -H 'Authorization: APIKey 112358' \
  -H 'Content-Type: application/json' \
  -d '{
    "WebHookUri": "http://localhost:8081",
    "Secret": "4d4829b57bab4eb7b642f69647512097",
    "Description": null,
    "IsPaused": false,
    "Filters": [
        "ticket:address_update"
    ],
    "Headers": {
        "X-CUSTOM": "Some value"
    },
    "Ezrid": [
        "13225","13142"
    ]

}'

Body of the request contains subscription data:

Name Type Mandatory Description
WebHookUri string yes URI of actor implemented webhook receiver
Secret string, length from 32 to 64 no String that may be used for additional notification encryption. Not used for now.
Description string no Notifcation description
IsPaused bool no If true notifications will be paused
Filters array of strings yes Array of notifications for subscription, see get available notifications description
Headers object no Object containing additional headers that should be sent to actor with notification data
Ezrid array of strings no Array of unit ID’s that incident report should relate to for notifications to be sent. If not specified, special “*” unit id is added, meaning that notifications will be sent for every incident report, disregarding related unit selection

Minimal request data:

{
	"WebHookUri": "http://localhost:8081",
	"Filters": ["ticket:address_update"]
}

Response:

{
    "Id": "4fd90d602bca4fdbb5910708b77fcd36",
    "WebHookUri": "http://localhost:8081",
    "Secret": "4d4829b57bab4eb7b642f69647512097",
    "Description": null,
    "IsPaused": false,
    "Filters": [
        "ticket:address_update"
    ],
    "Headers": {},
    "Properties": {},
    "Ezrid": [
        "*"
    ]
}

Status updates

Update event description

POST request at /api/eventdescription/update/<ticket-guid>

Example:

curl -X POST \
  .../api/eventdescription/update/C0FF83DC-F798-415A-A64D-77B12C35F22E \
  -H 'Authorization: APIKey 13123123' \
  -H 'Content-Type: application/json' \
  -d '{"eventdescription":"Some description less"}'

Response:

{}

Request data:

{
    "EventDescription":"Some description less"
}

Update activations

POST request at /api/activation/update/<ticket-guid>

Example:

curl -X POST \
  https://localhost:5002/api/activation/update/C0FF83DC-F798-415A-A64D-77B12C35F22E \
  -H 'Authorization: APIKey 123123123' \
  -H 'Content-Type: application/json' \
  -d '{
	"LocationId": 123,
	"LocationActivationId":12323,
	"Status":"active",
	"ETA": "2018-09-06T22:11:00"
}'

Request data:

Name Type Mandatory Description
LocationId integer yes Location id
LocationActivationId integer yes location activation id
Status string, One of the active, dispatched, onscene, unitretrieving, unitingarage, finished yes activation status
ETA string, ISO8601 encoded date no estimated time of arrival

Update location

POST request at /api/location/update/<ticket-guid>

Example:

curl -X POST \
  .../api/location/update/C0FF83DC-F798-415A-A64D-77B12C35F22E \
  -H 'Authorization: APIKey 123123' \
  -H 'Content-Type: application/json' \
  -d '{
	"X": 11.11,
	"Y": 12.12,
	"MuncipalityMid": 123123,
	"MunicipalityName": "MunName",
	"SettlementMid": 123123,
	"SettlementName": "SetName",
	"StreetMid": 123123,
	"StreetName": "StName",
	"HouseNumberMid": 123123,
	"FloorName": "FlName",
	"FloorAddition": "FlAddition"
}
'

Request data:

Name Type Mandatory Description
X double no X coordinate
Y double no X coordinate