From 9a6cccb222a4df73b4d956e7f2770799bc3fe727 Mon Sep 17 00:00:00 2001 From: Ian Renton Date: Sat, 8 Aug 2026 14:29:10 +0100 Subject: [PATCH] Upgrade notes in OpenAPI spec #119 --- static/apidocs/openapi.yml | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/static/apidocs/openapi.yml b/static/apidocs/openapi.yml index 49b627c..990c58f 100644 --- a/static/apidocs/openapi.yml +++ b/static/apidocs/openapi.yml @@ -27,6 +27,26 @@ info: * Added `sig_ref_data_providers`, `static_data_providers` and `callsign_data_providers` to `/status` response * Added `callsign_data_providers` to `/options` response + #### Upgrading a client from v1 to v2 API endpoints + + In v2.0 of Spothole, the `v1` API endpoints will be maintained for backwards compatibility, so I don't break everyone's + clients on day one. So if you have written a client against the `v1` API, you shouldn't notice anything breaking. + However, you are strongly encouraged to move to `v2` API endpoints as soon as possible. + + The good news is, even the breaking changes should have a relatively minor impact. If you just pull `/spots` and don't + specifically care about `dx_location_source="WAB/WAI GRID"`, you can just move to the `v2` endpoint with no issues. + Simply replace `v1` with `v2` in your code. If you do care specifically about `WAB/WAI GRID` in the `dx_location_source` + enum, note it's now just called `GRID`. + + If you POST spots to `/api/v1/spot`, in you just sent spot data such as `dx_call` at the top level of the data you + POST. With `v2` endpoints it needs to be one level down inside a `spot` object. This is to allow space for a new + top-level `handling` object which in later versions will allow you to control sending spots upstream to cluster and + xOTA sites. + + I don't think anyone was sending me QRZ/HamQTH credentials from their clients, or querying the `/options` call, so + updating clients for changes there should be confined to Spothole's own web interface. If you were doing that and + I haven't noticed, please carefully note the breaking changes listed above. + ### 1.5 No API changes.