Feature: Add zoom query parameter to Resources OpenAPI definition (#1852

)
SignalK · Dec 23, 2024 · 6c38520 · 6c38520
1 parent 8fdae2c
commit 6c38520
Show file tree

Hide file tree

Showing 2 changed files with 32 additions and 1 deletion.
diff --git a/docs/src/develop/rest-api/resources_api.md b/docs/src/develop/rest-api/resources_api.md
@@ -33,6 +33,7 @@ A filtered list of entries can be retrieved based on criteria such as:
 - being within a bounded area
 - distance from vessel
 - total entries returned
+- map zoom level
 
 by supplying a query string containing `key | value` pairs in the request.
 
@@ -54,6 +55,13 @@ _Example 3: Retrieve waypoints within a bounded area. Note: the bounded area is
 HTTP GET 'http://hostname:3000/signalk/v2/api/resources/waypoints?bbox=[-135.5,38,-134,38.5]'
 ```
 
+_Example 4: Return notes for display on a map view at zoom level 5. 
+
+```typescript
+HTTP GET 'http://hostname:3000/signalk/v2/api/resources/notes?zoom=5'
+```
+
+It is up to the provider to determine which resource entries are returned for any given zoom level. As a guide we recommend alignment with the criteria in the following document: https://wiki.openstreetmap.org/wiki/Zoom_levels_.
 
 ### Deleting Resources
 ---

diff --git a/src/api/resources/openApi.json b/src/api/resources/openApi.json
@@ -795,6 +795,17 @@
           "example": [135.5, -25.2]
         }
       },
+      "ZoomParam": {
+        "in": "query",
+        "name": "zoom",
+        "description": "Zoom level of the map used by the client to display the returned resource entries. Refer: [OSM Zoom Levels](https://wiki.openstreetmap.org/wiki/Zoom_levels)",
+        "schema": {
+          "type": "integer",
+          "format": "int32",
+          "minimum": 1,
+          "example": 4
+        }
+      },
       "ProviderParam": {
         "in": "query",
         "name": "provider",
@@ -828,7 +839,7 @@
         "summary": "Retrieve list of available resource types",
         "responses": {
           "default": {
-            "description": "List of avaialble resource types identified by name",
+            "description": "List of available resource types identified by name",
             "content": {
               "application/json": {
                 "schema": {
@@ -872,6 +883,9 @@
           },
           {
             "$ref": "#/components/parameters/PositionParam"
+          },
+          {
+            "$ref": "#/components/parameters/ZoomParam"
           }
         ],
         "responses": {
@@ -1002,6 +1016,9 @@
           },
           {
             "$ref": "#/components/parameters/PositionParam"
+          },
+          {
+            "$ref": "#/components/parameters/ZoomParam"
           }
         ],
         "responses": {
@@ -1132,6 +1149,9 @@
           },
           {
             "$ref": "#/components/parameters/PositionParam"
+          },
+          {
+            "$ref": "#/components/parameters/ZoomParam"
           }
         ],
         "responses": {
@@ -1263,6 +1283,9 @@
           {
             "$ref": "#/components/parameters/PositionParam"
           },
+          {
+            "$ref": "#/components/parameters/ZoomParam"
+          },
           {
             "name": "href",
             "in": "query",