Upgrade notes in OpenAPI spec #119

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.