w1cdn/spothole
1
0
Fork 0
mirror of https://git.ianrenton.com/ian/spothole.git synced 2026-09-25 00:34:32 +00:00
Code Issues 13 Packages Projects Releases Wiki Activity

Allow spots and alerts to have multiple activities #143

Browse Source
This commit is contained in:
Ian Renton
2026-09-24 22:57:46 +01:00
parent 81166dccab
commit 4477942bec
34 changed files with 217 additions and 157 deletions
Download Patch File Download Diff File Expand all files Collapse all files
static/apidocs/openapi.yml
+36 -24
View File
@@ -19,20 +19,20 @@ info:
The term "SIG" (Special Interest Group), which Spothole inherited from ADIF, has been replaced with "activity" throughout the API.
* **Breaking change:** In spot and alert data, `sig` has been renamed to `activity` and `sig_refs` to `activity_refs`.
* **Breaking change:** In activity reference data (i.e. each entry in `activity_refs`, and the response of the activity reference lookup), `sig` has been renamed to `activity`.
* **Breaking change:** In spot and alert data, the single `sig` value has been replaced with `activities`, a list of unique activity names. A spot or alert can now be associated with more than one activity (e.g. a POTA and WWFF dual activation, a /MM activation via satellite, etc). The array is empty if there is no associated activity. `sig_refs` has been renamed to `activity_refs`.
* **Breaking change:** In activity reference data (i.e. each entry in `activity_refs` of a spot or alert, and the response of the activity reference lookup), `sig` has been renamed to `activity`.
* **Breaking change:** The `dx_location_source` value "SIG REF LOOKUP" has been renamed to "ACTIVITY REF LOOKUP".
* **Breaking change:** The `/spots`, `/spots/stream`, `/alerts` and `/alerts/stream` query parameter `sig` has been renamed to `activity`, and its special value `NO_SIG` to `NO_ACTIVITY`. The `/spots` and `/spots/stream` query parameters `needs_sig` and `needs_sig_ref` have been renamed to `needs_activity` and `needs_activity_ref`. When using the `fields` query parameter, use the new field names `activity` and `activity_refs`.
* **Breaking change:** The `/spots`, `/spots/stream`, `/alerts` and `/alerts/stream` query parameter `sig` has been renamed to `activity`, and its special value `NO_SIG` to `NO_ACTIVITY`. The `/spots` and `/spots/stream` query parameters `needs_sig` and `needs_sig_ref` have been renamed to `needs_activity` and `needs_activity_ref`. The `activity` filter now matches any spot or alert that has at least one of the requested activities.
* **Breaking change:** `/lookup/sigref` has been renamed to `/lookup/activityref`, and its `sig` query parameter has been renamed to `activity`.
* **Breaking change:** POST `/spot` now expects `activity` and `activity_refs` in the `spot` object, rather than `sig` and `sig_refs`.
* **Breaking change:** POST `/spot` now expects `activities` (a list) and `activity_refs` in the `spot` object, rather than `sig` and `sig_refs`.
* **Breaking change:** In the `/options` response, `sigs` has been renamed to `activities`, and within each activity, `sig_type` has been renamed to `activity_type`.
* **Breaking change:** In the `/status` response, `sig_ref_data_providers` has been renamed to `activity_ref_data_providers`, and within each provider, `sig_name` has been renamed to `activity_name`.
#### Upgrading a client from v2 to v3 API endpoints
In v3.0 of Spothole, the `v2` (and `v1`) API endpoints will be maintained for backwards compatibility, so if you have written a client against the `v2` API, it will continue to receive `sig`, `sig_refs` etc. as before. However, you are encouraged to move to the `v3` API endpoints as soon as possible.
To upgrade, replace `v2` with `v3` in the URLs your code calls, then rename any use of the fields, query parameters and values listed above. If you use the activity reference lookup, call `/lookup/activityref?activity=...&id=...` instead of `/lookup/sigref?sig=...&id=...`.
In v3.0 of Spothole, the `v2` (and `v1`) API endpoints will be maintained for backwards compatibility, so if you have written a client against the `v2` API, it will continue to receive `sig`, `sig_refs` etc. as before. Where a spot or alert has more than one activity, the `v2` and `v1` APIs will return only the first one as `sig`.
You are encouraged to move to the `v3` API endpoints as soon as possible. To upgrade, replace `v2` with `v3` in the URLs your code calls, then rename any use of the fields, query parameters and values listed above, and handle `activities` being a list rather than a single `sig` value. If you use the activity reference lookup, call `/lookup/activityref?activity=...&id=...` instead of `/lookup/sigref?sig=...&id=...`.
### 2.2
@@ -582,11 +582,11 @@ components:
in: query
description: >
Limit the spots to only ones from one or more activities provided as an argument.
To select more than one activity, supply a comma-separated list. The special `activity` name `NO_ACTIVITY`
matches spots with no activity set. You can use `activity=NO_ACTIVITY` to specifically only return generic
spots with no associated activity. You can also use combinations to request for example POTA + no
activity, but reject other activities. If you want to request 'every activity and not No Activity', see the
`needs_activity` query parameter for a shortcut.
To select more than one activity, supply a comma-separated list. A spot matches if any of its activities are
in the list. The special `activity` name `NO_ACTIVITY` matches spots with no activity set. You can use
`activity=NO_ACTIVITY` to specifically only return generic spots with no associated activity. You can also use
combinations to request for example POTA + no activity, but reject other activities. If you want to request
'every activity but not No Activity', see the `needs_activity` query parameter for a shortcut.
schema:
$ref: "#/components/schemas/ActivityNameIncludingNoActivity"
SpotNeedsActivity:
@@ -746,8 +746,7 @@ components:
in: query
description: >
Limit the alerts to only ones from one or more activities. To select more than one
activity, supply a comma-separated list. The special value 'NO_ACTIVITY' can be included to return alerts
specifically without an associated activity.
activity, supply a comma-separated list. An alert matches if any of its activities are in the list.
schema:
$ref: "#/components/schemas/ActivityNameIncludingNoActivity"
AlertDxContinent:
@@ -1334,9 +1333,16 @@ components:
type: string
description: Comment left by the spotter, if any
example: "59 in NY 73"
activity:
description: Activity, e.g. outdoor activity programme such as POTA
$ref: "#/components/schemas/ActivityName"
activities:
type: array
uniqueItems: true
items:
$ref: "#/components/schemas/ActivityName"
description: >
Activities, e.g. outdoor activity programmes such as POTA. There may be more than one, e.g. for a POTA plus
WWFF dual activation, or none. Each activity appears at most once. The first activity is the "primary" one,
e.g. the activity of the programme the spot came from, and is the one used to choose the icon.
example: [ "POTA", "WWFF" ]
activity_refs:
type: array
items:
@@ -1382,10 +1388,9 @@ components:
submit_upstream:
type: boolean
description: >
If true, forward the spot to an external upstream provider (e.g. POTA, SOTA) rather
than only adding it to this Spothole server. Requires `activity`, at least one `activity_refs`
entry, and `upstream_provider` to be set. Check `spot_submit_providers` in the
/options response to see which activities and providers support this.
If true, forward the spot to an external upstream provider (e.g. POTA, SOTA) rather than only adding it
to this Spothole server. Requires `upstream_provider` to be set. Check `spot_submit_providers` in the
`/options` response to see which activities and providers support this.
default: false
upstream_provider:
type: string
@@ -1522,9 +1527,16 @@ components:
type: string
description: Comment made by the activator, if any
example: "2025 DXpedition to null island"
activity:
description: Activity, e.g. outdoor activity programme such as POTA
$ref: "#/components/schemas/ActivityName"
activities:
type: array
uniqueItems: true
items:
$ref: "#/components/schemas/ActivityName"
description: >
Activities, e.g. outdoor activity programmes such as POTA. There may be more than one, e.g. for a POTA and
WWFF dual activation, or none. Each activity appears at most once. The first activity is the "primary" one,
e.g. the activity of the programme the spot came from, and is the one used to choose the icon.
example: [ "POTA", "WWFF" ]
activity_refs:
type: array
items: