ogn-ddb: A new API

README.md

A new OGN-DDB API

inspired by the Skylines API Draft and the Github API.

• Available over HTTPS-only at https://ddb.glidernet.org/api/
• Versioning by URL, starting with /v2 (to reduce the danger of confusion with the old API at /download)
• All data is sent and received as JSON
• Blank fields are included as null

Authentication

• HTTP Basic Auth only (for now)

User Agent Required

• User-Agent header is required and must not be empty
• Requests without User-Agent header are rejected with 403 Forbidden

CORS

• Every Origin is allowed

Pagination ?

• pagination is undesirable for the list of all (trackable) devices if fetched by a receiver
• otherwise it's desirable (in combination with the link header)

Resources

see API resources

API.md

Endpoints

Devices

List devices

GET /devices

Parameters

Name	Type	Description
tracked	boolean	Indicates the tracked state of the devices to return. Default: null
identified	boolean	Indicates the identified state of the devices to return. Default: null
ids	string	A comma-separated list of device ids.

Response

Status: 200 OK

[
{
  "id": "0123BC",
  "type": "F",
  "aircraft_model_id": 209,
  "aircraft_model_name": "LS-4",
  "aircraft_model_category": "glider",
  "aircraft_registration": "X-0123",
  "aircraft_competition_id": "X01",
  "tracked": true,
  "identified": true
},
{
  "id": "DEADBE",
  "type": "F",
  "aircraft_model_id": 112,
  "aircraft_model_name": "DR-400",
  "aircraft_model_category": "plane",
  "aircraft_registration": "X-EABC",
  "aircraft_competition_id": null,
  "tracked": false,
  "identified": false
}
]

Get a single device

GET /devices/:id

Response

Status: 200 OK

{
  "id": "DEADBE",
  "type": "F",
  "aircraft_model_id": 112,
  "aircraft_model_name": "DR-400",
  "aircraft_model_category": "plane",
  "aircraft_registration": "X-EABC",
  "aircraft_competition_id": "LOL",
  "tracked": true,
  "identified": true
}

Create a device

POST /devices

Parameters

Name	Type	Description (possible values)
id	string	Required. The device id of the device, also known as FLARM-Radio-ID or OGN address (^[A-F0-9]{6}$).
type	string	Required. The type of the device (F: FLARM, O: OGN Tracker, I: FLARM with ICAO code as device id).
aircraft_model_id	integer	The model id of the aircraft which is equipped with the device, see also List aircraft models
aircraft_registration	string	The registration of the aircraft which is equipped with the device (utf-8, maximum length is 7 characters).
aircraft_competition_id	string	The competition id of the aircraft which is equipped with the device (utf-8, maximum length is 3 characters).
tracked	boolean	The tracked state of the device.
identified	boolean	The identified state of the device.

Example

{
  "id": "DEADBE",
  "type": "F",
  "aircraft_model_id": 112,
  "aircraft_registration": "X-EABC",
  "aircraft_competition_id": "XXL",
  "tracked": true,
  "identified": true
}

Response

Status: 201 Created
Location: https://ddb.glidernet.org/api/v1/devices/DEADBE

{
  "id": "DEADBE",
  "type": "F",
  "aircraft_model_id": 112,
  "aircraft_model_name": "DR-400",
  "aircraft_model_category": "plane",
  "aircraft_registration": "X-EABC",
  "aircraft_competition_id": "XXL",
  "tracked": false,
  "identified": false
}

Edit a device

PATCH /devices/:id

Parameters

Name	Type	Description (possible values)
type	string	Required. The type of the device (F: FLARM, O: OGN Tracker, I: FLARM with ICAO code as device id).
aircraft_model_id	integer	The model id of the aircraft which is equipped with the device, see also List aircraft models
aircraft_registration	string	The registration of the aircraft which is equipped with the device (utf-8, maximum length is 7 characters).
aircraft_competition_id	string	The competition id of the aircraft which is equipped with the device (utf-8, maximum length is 3 characters).
tracked	boolean	The tracked state of the device.
identified	boolean	The identified state of the device.

Example

{
  "type": "F",
  "aircraft_model_id": 209,
  "aircraft_registration": "X-0123",
  "aircraft_competition_id": "X01",
  "tracked": true,
  "identified": true
}

Response

Status: 200 OK

{
  "id": "DEADBE",
  "type": "F",
  "aircraft_model_id": 209,
  "aircraft_model_name": "LS-4",
  "aircraft_model_category": "glider",
  "aircraft_registration": "X-0123",
  "aircraft_competition_id": "X01",
  "tracked": true,
  "identified": true
}

Remove a device

DELETE /devices/:id

Response

Status: 204 No Content

Aircraft models

List aircraft models

GET /aircraft_models

Response

Status: 200 OK

[
{
  "id": 112,
  "name": "DR-400",
  "category": "plane"
},
{
  "id": 209,
  "name": "LS-4",
  "category": "glider"
}
]

Get a single aircraft model

GET /aircraft_models/:id

Response

Status: 200 OK

{
  "id": 112,
  "name": "DR-400",
  "category": "plane"
}