api: Add additional bindings to filter end devices and gateways

TheThingsNetwork · Sep 17, 2024 · f22acbe · f22acbe
1 parent 1989acd
commit f22acbe
Show file tree

Hide file tree

Showing 10 changed files with 621 additions and 249 deletions.
diff --git a/api/ttn/lorawan/v3/api.md b/api/ttn/lorawan/v3/api.md
@@ -4796,6 +4796,7 @@ NsEndDeviceRegistry, the AsEndDeviceRegistry and the JsEndDeviceRegistry.
 | `Create` | `POST` | `/api/v3/applications/{end_device.ids.application_ids.application_id}/devices` | `*` |
 | `Get` | `GET` | `/api/v3/applications/{end_device_ids.application_ids.application_id}/devices/{end_device_ids.device_id}` |  |
 | `List` | `GET` | `/api/v3/applications/{application_ids.application_id}/devices` |  |
+| `List` | `POST` | `/api/v3/applications/{application_ids.application_id}/devices/filter` | `*` |
 | `Update` | `PUT` | `/api/v3/applications/{end_device.ids.application_ids.application_id}/devices/{end_device.ids.device_id}` | `*` |
 | `Delete` | `DELETE` | `/api/v3/applications/{application_ids.application_id}/devices/{device_id}` |  |
 
@@ -6092,6 +6093,7 @@ gateway registrations.
 | `List` | `GET` | `/api/v3/gateways` |  |
 | `List` | `GET` | `/api/v3/users/{collaborator.user_ids.user_id}/gateways` |  |
 | `List` | `GET` | `/api/v3/organizations/{collaborator.organization_ids.organization_id}/gateways` |  |
+| `List` | `POST` | `/api/v3/gateways/filter` | `*` |
 | `Update` | `PUT` | `/api/v3/gateways/{gateway.ids.gateway_id}` | `*` |
 | `Delete` | `DELETE` | `/api/v3/gateways/{gateway_id}` |  |
 | `Restore` | `POST` | `/api/v3/gateways/{gateway_id}/restore` |  |

diff --git a/api/ttn/lorawan/v3/api.swagger.json b/api/ttn/lorawan/v3/api.swagger.json
@@ -1181,6 +1181,45 @@
         ]
       }
     },
+    "/applications/{application_ids.application_id}/devices/filter": {
+      "post": {
+        "summary": "List end devices in the given application.\nSimilar to Get, this selects the fields given by the field mask.\nMore or less fields may be returned, depending on the rights of the caller.",
+        "operationId": "EndDeviceRegistry_List2",
+        "responses": {
+          "200": {
+            "description": "A successful response.",
+            "schema": {
+              "$ref": "#/definitions/v3EndDevices"
+            }
+          },
+          "default": {
+            "description": "An unexpected error response.",
+            "schema": {
+              "$ref": "#/definitions/googlerpcStatus"
+            }
+          }
+        },
+        "parameters": [
+          {
+            "name": "application_ids.application_id",
+            "in": "path",
+            "required": true,
+            "type": "string"
+          },
+          {
+            "name": "body",
+            "in": "body",
+            "required": true,
+            "schema": {
+              "$ref": "#/definitions/v3EndDeviceRegistryListBody"
+            }
+          }
+        ],
+        "tags": [
+          "EndDeviceRegistry"
+        ]
+      }
+    },
     "/applications/{application_ids.application_id}/devices/{device_id}": {
       "delete": {
         "summary": "Delete the end device with the given IDs.",
@@ -6813,6 +6852,39 @@
         ]
       }
     },
+    "/gateways/filter": {
+      "post": {
+        "summary": "List gateways where the given user or organization is a direct collaborator.\nIf no user or organization is given, this returns the gateways the caller\nhas access to.\nSimilar to Get, this selects the fields given by the field mask.\nMore or less fields may be returned, depending on the rights of the caller.",
+        "operationId": "GatewayRegistry_List4",
+        "responses": {
+          "200": {
+            "description": "A successful response.",
+            "schema": {
+              "$ref": "#/definitions/v3Gateways"
+            }
+          },
+          "default": {
+            "description": "An unexpected error response.",
+            "schema": {
+              "$ref": "#/definitions/googlerpcStatus"
+            }
+          }
+        },
+        "parameters": [
+          {
+            "name": "body",
+            "in": "body",
+            "required": true,
+            "schema": {
+              "$ref": "#/definitions/v3ListGatewaysRequest"
+            }
+          }
+        ],
+        "tags": [
+          "GatewayRegistry"
+        ]
+      }
+    },
     "/gateways/rights/batch": {
       "get": {
         "summary": "Assert that the caller has the requested rights on all the requested gateways.\nThe check is successful if there are no errors.",
@@ -23403,6 +23475,39 @@
         }
       }
     },
+    "v3EndDeviceRegistryListBody": {
+      "type": "object",
+      "properties": {
+        "application_ids": {
+          "type": "object"
+        },
+        "field_mask": {
+          "type": "string",
+          "description": "The names of the end device fields that should be returned.\nSee the API reference for which fields can be returned by the different services."
+        },
+        "order": {
+          "type": "string",
+          "description": "Order the results by this field path (must be present in the field mask).\nDefault ordering is by ID. Prepend with a minus (-) to reverse the order."
+        },
+        "limit": {
+          "type": "integer",
+          "format": "int64",
+          "description": "Limit the number of results per page."
+        },
+        "page": {
+          "type": "integer",
+          "format": "int64",
+          "description": "Page number for pagination. 0 is interpreted as 1."
+        },
+        "filters": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "$ref": "#/definitions/v3ListEndDevicesRequestFilter"
+          }
+        }
+      }
+    },
     "v3EndDeviceRegistryUpdateBody": {
       "type": "object",
       "properties": {
@@ -25474,6 +25579,44 @@
         }
       }
     },
+    "v3ListGatewaysRequest": {
+      "type": "object",
+      "properties": {
+        "collaborator": {
+          "$ref": "#/definitions/v3OrganizationOrUserIdentifiers",
+          "description": "By default we list all gateways the caller has rights on.\nSet the user or the organization (not both) to instead list the gateways\nwhere the user or organization is collaborator on."
+        },
+        "field_mask": {
+          "type": "string",
+          "description": "The names of the gateway fields that should be returned."
+        },
+        "order": {
+          "type": "string",
+          "description": "Order the results by this field path (must be present in the field mask).\nDefault ordering is by ID. Prepend with a minus (-) to reverse the order."
+        },
+        "limit": {
+          "type": "integer",
+          "format": "int64",
+          "description": "Limit the number of results per page."
+        },
+        "page": {
+          "type": "integer",
+          "format": "int64",
+          "description": "Page number for pagination. 0 is interpreted as 1."
+        },
+        "deleted": {
+          "type": "boolean",
+          "description": "Only return recently deleted gateways."
+        },
+        "filters": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "$ref": "#/definitions/v3ListGatewaysRequestFilter"
+          }
+        }
+      }
+    },
     "v3ListGatewaysRequestFilter": {
       "type": "object",
       "properties": {

diff --git a/api/ttn/lorawan/v3/end_device_services.proto b/api/ttn/lorawan/v3/end_device_services.proto
@@ -63,7 +63,13 @@ service EndDeviceRegistry {
   // Similar to Get, this selects the fields given by the field mask.
   // More or less fields may be returned, depending on the rights of the caller.
   rpc List(ListEndDevicesRequest) returns (EndDevices) {
-    option (google.api.http) = {get: "/applications/{application_ids.application_id}/devices"};
+    option (google.api.http) = {
+      get: "/applications/{application_ids.application_id}/devices"
+      additional_bindings {
+        post: "/applications/{application_ids.application_id}/devices/filter"
+        body: "*"
+      }
+    };
   }
 
   // Update the end device, changing the fields specified by the field mask to the provided values.

diff --git a/api/ttn/lorawan/v3/gateway_services.proto b/api/ttn/lorawan/v3/gateway_services.proto
@@ -64,6 +64,10 @@ service GatewayRegistry {
       get: "/gateways"
       additional_bindings {get: "/users/{collaborator.user_ids.user_id}/gateways"}
       additional_bindings {get: "/organizations/{collaborator.organization_ids.organization_id}/gateways"}
+      additional_bindings {
+        post: "/gateways/filter"
+        body: "*"
+      }
     };
   }