From 6c38520f3a2fffed0a797d845da35e3dc57112eb Mon Sep 17 00:00:00 2001
From: AdrianP <38519157+panaaj@users.noreply.github.com>
Date: Mon, 23 Dec 2024 16:01:40 +1030
Subject: [PATCH] Feature: Add zoom query parameter to Resources OpenAPI
 definition (#1852)

---
 docs/src/develop/rest-api/resources_api.md |  8 +++++++
 src/api/resources/openApi.json             | 25 +++++++++++++++++++++-
 2 files changed, 32 insertions(+), 1 deletion(-)

diff --git a/docs/src/develop/rest-api/resources_api.md b/docs/src/develop/rest-api/resources_api.md
index c4c7386aa..005b1f014 100644
--- 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
index 2bc0fcfb2..c927fd037 100644
--- 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",