{ "openapi": "3.0.3", "info": { "title": "Endpoint Register REST", "version": "v1", "description": "" }, "servers": [ { "url": "https://cloud.kaaiot.com/epr/api/v1", "description": "API Server" } ], "paths": { "/endpoints": { "post": { "description": "Registers a new endpoint within a specified application version.", "responses": { "201": { "description": "Endpoint successfully registered within the application version.", "headers": { "Location": { "description": "URI in format `{schema}://{host}/epr/api/v1/endpoints/{endpointId}`", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EndpointRegistrationResponse" }, "example": { "token": "02226466-e744-48ac-8f0c-a57fe4e77de4", "status": "Inactive", "relations": { "successful": [ { "type": "contains", "from": "67b27f9b-c4d1-41dc-b21f-2917b74c467a", "to": "f359de38-6763-11ed-9022-0242ac120002" } ], "failed": [ { "type": "contains", "from": "518ab0c0-e505-4062-9f1f-408da7b3ea05", "to": "67b27f9b-c4d1-41dc-b21f-2917b74c467a", "message": "Only one inbound relation with relation type [CONTAINS] is allowed" } ] } } } } }, "404": { "description": "Relation endpoint not found or querying user is not authorized for it." } }, "security": [ { "oauth_2_0": [ "application:endpoint:create", "endpoint:update" ] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EndpointRegistrationRequest" }, "example": { "appVersion": { "name": "bqa46oeg14m0thoh7g0l-v1" }, "metadata": { "level": 3, "room": 234 }, "endpointToken": "a57fe4e77de4", "endpointId": "67b27f9b-c4d1-41dc-b21f-2917b74c467a", "relations": [ { "type": "contains", "to": "f359de38-6763-11ed-9022-0242ac120002" }, { "type": "contains", "from": "518ab0c0-e505-4062-9f1f-408da7b3ea05" } ], "resourceGroupIds": [ "aXJuOmFjY291bnQ6aWFtY29yZTprYWE6OnBvb2wvZGV2aWNlcw==" ] } } } } }, "get": { "description": "Returns information about endpoints that match query parameters.", "responses": { "200": { "description": "Endpoints are successfully retrieved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageInfo" }, "example": { "totalElements": 1, "content": [ { "endpointId": "5a67aa97-1f5c-41eb-a066-8e004157062b", "createdDate": "2017-04-20T11:19:57.848Z", "appName": "bqa46oeg14m0thoh7g0l", "appVersion": { "name": "example_app_v1", "registeredDate": "2017-04-20T11:19:57.848Z" }, "metadata": { "OS": { "type": "Linux", "version": "4.10.6" }, "tag": { "id": "1" }, "anyJsonType": [ 11 ] }, "metadataUpdatedDate": "2017-04-20T12:07:19.112Z", "filters": [ "9e569809-e316-422f-851e-8d916ea0e89a" ] } ] } } } } }, "security": [ { "oauth_2_0": [ "endpoint:read" ] } ], "parameters": [ { "name": "endpointId", "in": "query", "description": "Endpoint identifier, can be one or multiple.", "required": false, "schema": { "type": "string" }, "example": "79c717d9-eedd-4f71-b9f8-86caf7e309e4" }, { "name": "applicationName", "in": "query", "description": "Filters endpoints by application name, can be one or multiple.", "required": false, "schema": { "type": "string" }, "example": "my-application" }, { "name": "applicationVersionName", "in": "query", "description": "Filters endpoints by application version name.", "required": false, "schema": { "type": "string" }, "example": "my-application-version" }, { "name": "tenantId", "in": "query", "description": "ID of the tenant endpoints belong to.", "required": false, "schema": { "type": "string" }, "example": "5b39397d-1be2-49a1-ad8b-f641a97e4ce3" }, { "name": "offset", "in": "query", "description": "Start index that the server should return data from.", "required": false, "schema": { "type": "integer" }, "example": 0 }, { "name": "limit", "in": "query", "description": "Maximum number of items to return. To get all items limit must be 0.", "required": false, "schema": { "type": "integer", "default": 100 }, "example": 1 }, { "name": "metadataFilter", "in": "query", "description": "Filter endpoints by a multiple metadata key-value pairs.\n
\n**NOTE** Unsafe ASCII characters in the URL must be encoded according to Uniform Resource Locators RFC.\n", "required": false, "schema": { "type": "string" } }, { "name": "multiFilter", "in": "query", "description": "Filter endpoints by a metadata.\n
\n**NOTE** Unsafe ASCII characters in the URL must be encoded according to Uniform Resource Locators RFC.\n", "required": false, "schema": { "type": "string" } }, { "name": "regex", "in": "query", "description": "Regex to match endpoints by.\nFields that participate in the match: ID, metadata keys and values, application version name.\n", "required": false, "schema": { "type": "string" }, "example": "linux*" }, { "name": "filterId", "in": "query", "description": "Filter endpoints by matching filter ID(s).\nIf multiple `filterId` specified, the resultset will contain only endpoints that match all filters.\nOnly querying by the filters with `active` status is allowed.\n", "required": false, "schema": { "type": "string" } }, { "name": "metadataKeys", "in": "query", "description": "Only return specified metadata keys in the response.\nWhen specified, metadata is implicitly included (no need to also pass `include=metadata`).\n
Keys must contain only Latin letters, digits, and underscores.\n", "required": false, "schema": { "type": "string" }, "example": "/endpoints?metadataKeys=OS&metadataKeys=country" } ] } }, "/endpoints/search": { "post": { "description": "Searches endpoints.", "responses": { "200": { "description": "Response 200", "content": { "application/json": { "schema": { "type": "object" }, "example": { "totalElements": 1, "content": [ { "endpointId": "5a67aa97-1f5c-41eb-a066-8e004157062b", "createdDate": "2017-04-20T11:19:57.848Z", "appName": "bqa46oeg14m0thoh7g0l", "appVersion": { "name": "example_app_v1", "registeredDate": "2017-04-20T11:19:57.848Z" }, "metadata": { "OS": { "type": "Linux", "version": "4.10.6" }, "tag": { "id": "1" }, "anyJsonType": [ 11 ] }, "metadataUpdatedDate": "2017-04-20T12:07:19.112Z", "filters": [ "9e569809-e316-422f-851e-8d916ea0e89a" ] } ] } } } } }, "security": [ { "oauth_2_0": [ "endpoint:read" ] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MultiFilter" }, "example": { "and": [ { "key": "OS", "operator": "IN", "values": [ "Linux" ], "or": [ { "key": "region", "operator": "IN", "values": [ "us-east" ] }, { "key": "region", "operator": "IN", "values": [ "eu-west" ] } ] }, { "key": "endpointId", "operator": "NOT_IN", "values": [ "33b29787-d738-41e3-8252-5b9ddd51c65c" ] }, { "operator": "IN_REGEX", "values": [ "linux.*" ] }, { "key": "installDate", "operator": "GREATER_THAN_OR_IN", "values": [ "2024-01-01" ] }, { "key": "installDate", "operator": "LESS_THAN", "values": [ "2024-12-31" ] }, { "key": "createdDate", "operator": "GREATER_THAN_OR_IN", "values": [ "2024-01-01T00:00:00" ] }, { "key": "appVersion.registeredDate", "operator": "LESS_THAN", "values": [ "2024-12-31T23:59:59" ] } ], "filterIds": [ "my-filter-id" ], "sort": "system_load", "sortOrder": "desc", "offset": 0, "limit": 10 } } } } } }, "/endpoints/delete": { "post": { "description": "Deletes endpoints in batch.", "responses": { "204": { "description": "Endpoints are successfully deleted." } }, "security": [ { "oauth_2_0": [ "endpoint:delete" ] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchDeleteRequest" }, "example": { "multiFilter": { "and": [ { "key": "OS", "operator": "IN", "values": [ "Linux" ] }, { "key": "endpointId", "operator": "NOT_IN", "values": [ "33b29787-d738-41e3-8252-5b9ddd51c65c" ] } ] } } } } } } }, "/endpoints/batch": { "post": { "description": "Create a task to register a batch of endpoints within a specified application version.", "responses": { "202": { "description": "Batch endpoint registration task is accepted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchEndpointRegistrationAcceptedResponse" }, "example": { "taskId": "79c717d9-eedd-4f71-b9f8-86caf69809e4" } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientErrorResponse" } } } }, "403": { "description": "User does not have permissions to perform this operation." } }, "security": [ { "oauth_2_0": [ "application:endpoint:create" ] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EndpointBatchRegistrationRequest" }, "example": { "appVersion": { "name": "example_app_v1" }, "endpoints": [ { "endpointToken": "02226466-e744-48ac-8f0c-a57fe4e77de4", "metadata": { "level": 3, "room": 234 } }, { "endpointToken": "02226466-e744-48ac-8f0c-a57fe4e35db2", "metadata": { "level": 2, "room": 125 } }, { "endpointToken": "02226466-e744-48ac-8f0c-a57fe4f48d5f" } ] } } } } } }, "/endpoints/batch/status": { "get": { "description": "Returns batch endpoints registration task status.", "responses": { "200": { "description": "Batch endpoint registration task's status is successfully retrieved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchEndpointRegistrationStatusResponse" }, "example": { "createdCount": 2, "failedCount": 1, "created": [ { "endpointId": "56726466-e454-23ac-340c-f34fefda7de4", "endpointToken": "02226466-e744-48ac-8f0c-a57fe4e77de4" }, { "endpointId": "56726466-e454-23ac-340c-f34fefda7df2", "endpointToken": "02226466-e744-48ac-8f0c-a57fe4e35db2" } ], "failed": [ { "endpointToken": "02226466-e744-48ac-8f0c-a57fe4f48d5f", "statusReason": "Endpoint token already exists." } ] } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "type": "object" } } } } }, "security": [ { "oauth_2_0": [ "application:endpoint:create" ] } ], "parameters": [ { "name": "appName", "in": "query", "description": "Application name.", "required": true, "schema": { "type": "string" }, "example": "smart-kettle" }, { "name": "taskId", "in": "query", "description": "Batch endpoint registration task ID.", "required": true, "schema": { "type": "string" }, "example": "79c717d9-eedd-4f71-b9f8-86caf69809e4" } ] } }, "/endpoints/{endpointId}": { "parameters": [ { "name": "endpointId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Identifier of the endpoint to operate on.", "example": "79c717d9-eedd-4f71-b9f8-86caf7e309e4" } ], "get": { "description": "Returns endpoint information.", "responses": { "200": { "description": "Object successfully retrieved.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "endpointId": "69c4c970-94ce-4608-bf36-736d16fdab82", "createdDate": "2017-04-20T11:19:57.848Z", "appName": "bqa46oeg14m0thoh7g0l", "appVersion": { "name": "example_app_v1", "registeredDate": "2017-04-20T11:19:57.848Z" }, "metadata": { "OS": { "type": "Linux", "version": "4.10.6" }, "tag": { "id": "1" }, "anyJsonType": [ 11 ] }, "metadataUpdatedDate": "2017-04-20T15:01:12.144Z", "filters": [ "58229325-8444-4394-a4c2-1ef2b44160f5" ], "poolIds": [ "aXJuOnJjNzNkYmg3cTA6aWFtY29yZTo0YXRjaWNuaXNnOjpwb29sL2Rldg==" ] } } } }, "400": { "description": "Invalid `include` query parameter.", "content": { "application/json": { "schema": { "type": "object" } } } } }, "security": [ { "oauth_2_0": [ "endpoint:read" ] } ], "parameters": [ { "name": "tenantId", "in": "query", "description": "ID of the tenant the endpoint belong to.", "required": false, "schema": { "type": "string" }, "example": "5b39397d-1be2-49a1-ad8b-f641a97e4ce3" } ] }, "delete": { "description": "Deletes endpoint.", "responses": { "204": { "description": "Endpoint is successfully deleted." } }, "security": [ { "oauth_2_0": [ "endpoint:delete" ] } ] } }, "/endpoints/{endpointId}/relations": { "parameters": [ { "name": "endpointId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Identifier of the endpoint to operate on.", "example": "79c717d9-eedd-4f71-b9f8-86caf7e309e4" } ], "get": { "description": "Returns all available relations for the given endpoint ID.", "responses": { "200": { "description": "Endpoint relations successfully retrieved.", "content": { "application/json": { "schema": { "type": "object" }, "example": [ "69c4c970-94ce-4608-bf36-7b8236d16fda", "f359de38-6763-11ed-9022-0242ac120002" ] } } }, "404": { "description": "Endpoint not found." } }, "security": [ { "oauth_2_0": [ "endpoint:read" ] } ], "parameters": [ { "name": "relation", "in": "query", "description": "Filters endpoints by relation type and its direction.\n`contains` will return all endpoints with the inbound direction coming from the querying endpont - e.g., if quering endpoint represents a room, this type of query will return all sensors in that room.\n`!contains` will return all endpoints with the outbound direction coming to the querying endpoint - e.g., if quering endpoint represents a sensor, this type of query will return a room that contains it.\n", "required": true, "schema": { "type": "string", "enum": [ "contains", "!contains" ] }, "example": "!contains" } ] } }, "/endpoints/{endpointId}/app-version": { "parameters": [ { "name": "endpointId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Identifier of the endpoint to operate on.", "example": "79c717d9-eedd-4f71-b9f8-86caf7e309e4" } ], "get": { "description": "Returns endpoint registration data within application version.", "responses": { "200": { "description": "Endpoint registration data retrieved successfully.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "name": "example_app_v1", "registeredDate": "2017-04-20T11:19:57.848Z" } } } } } }, "put": { "description": "Updates endpoint registration data with the application version.", "responses": { "204": { "description": "Endpoint registration data updated successfully." }, "400": { "description": "Invalid application version name.", "content": { "application/json": { "schema": { "type": "object" } } } } }, "security": [ { "oauth_2_0": [ "endpoint:update" ] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object" }, "example": { "name": "example_app_v2" } } } } } }, "/endpoints/{endpointId}/metadata": { "parameters": [ { "name": "endpointId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Identifier of the endpoint to operate on.", "example": "79c717d9-eedd-4f71-b9f8-86caf7e309e4" } ], "get": { "description": "Returns all metadata or requested metadata keys (must be a non-empty string containing Latin letters, digits, and underscores only) for a specific endpoint.", "responses": { "200": { "description": "Endpoint metadata of the specified endpoint.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "OS": { "type": "Linux", "version": "4.10.6" }, "tag": { "id": "1" }, "anyJsonType": [ 11 ] } } } }, "400": { "description": "Metadata keys are not valid." } }, "security": [ { "oauth_2_0": [ "endpoint:read" ] } ], "parameters": [ { "name": "include", "in": "query", "description": "Only fields that match any of the `include` parameters are returned.\n
If not specified, all fields are returned.\n", "required": false, "schema": { "type": "string" }, "example": "/endpoints/{endpointId}/metadata?include=key1&include=key2" } ] }, "put": { "description": "Updates an endpoint metadata.\n
Endpoint metadata consists of multiple key-value pairs (called fields) where keys must be non-empty strings containing Latin letters, digits, and underscores only, while the values can be of any JSON type.\n", "responses": { "204": { "description": "Endpoint metadata successfully updated." }, "400": { "description": "Payload is not a JSON object or metadata keys are not valid." } }, "security": [ { "oauth_2_0": [ "endpoint:update" ] } ], "parameters": [ { "name": "inheritedMetadata", "in": "query", "description": "Defines how inherited metadata should be handled.", "required": false, "schema": { "type": "string", "enum": [ "SKIP", "UPDATE" ] } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object" }, "example": { "OS": { "type": "Linux", "version": "4.10.6" }, "tag": { "id": "1" }, "anyJsonType": [ 11 ] } } } } }, "patch": { "description": "Applies JSON Patch to the endpoint metadata. If no metadata exists, it is created.\nMetadata keys must be non-empty strings containing Latin letters, digits, and underscores only.\n", "responses": { "200": { "description": "Endpoint metadata successfully patched.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "OS": { "type": "Linux", "version": "4.10.6" }, "tag": { "id": "1" }, "anyJsonType": [ 11 ] } } } }, "400": { "description": "Invalid JSON Patch format or metadata keys are not valid." } }, "security": [ { "oauth_2_0": [ "endpoint:update" ] } ], "requestBody": { "content": { "application/json-patch+json": { "schema": { "type": "array" }, "example": [ { "op": "add", "path": "/location", "value": { "city": "Kiev", "street": "Nyzhnoiurkivska" } }, { "op": "remove", "path": "/anyJsonType/0" }, { "op": "move", "from": "/OS", "path": "/tag" } ] } } } } }, "/endpoints/{endpointId}/metadata/{metadataKey}": { "parameters": [ { "name": "endpointId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Identifier of the endpoint to operate on.", "example": "79c717d9-eedd-4f71-b9f8-86caf7e309e4" }, { "name": "metadataKey", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Metadata key must be a non-empty string containing Latin letters, digits, and underscores only.", "example": "OS" } ], "get": { "description": "Returns metadata value for the specified key.", "responses": { "200": { "description": "Metadata value for the specified key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EndpointMetadataValue" } } } }, "400": { "description": "Bad request." } }, "security": [ { "oauth_2_0": [ "endpoint:read" ] } ] }, "put": { "description": "Creates and updates single endpoint metadata field.", "responses": { "200": { "description": "Single endpoint metadata key-value pair successfully updated.\n", "content": { "application/json": { "schema": { "type": "object" } } } }, "201": { "description": "Single endpoint metadata key-value pair successfully created.\n", "headers": { "Location": { "description": "Location of the newly created endpoint metadata key-value pair.\nThe format is as follows:\n{schema}://{host}:{port}/api/{version}/endpoints/{endpointId}/metadata/{metadataKey}\n", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid JSON value or metadata key is not valid." } }, "security": [ { "oauth_2_0": [ "endpoint:update" ] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object" } } } } }, "delete": { "description": "Deletes single endpoint metadata field for a specific endpoint.", "responses": { "204": { "description": "Endpoint metadata key successfully deleted." }, "400": { "description": "Invalid metadata key." } }, "security": [ { "oauth_2_0": [ "endpoint:update" ] } ] } }, "/endpoints/{endpointId}/metadata-keys": { "parameters": [ { "name": "endpointId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Identifier of the endpoint to operate on.", "example": "79c717d9-eedd-4f71-b9f8-86caf7e309e4" } ], "get": { "description": "Returns all endpoint metadata keys for the specified endpoint.", "responses": { "200": { "description": "Array that contains all metadata fields.", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/applications/{applicationName}/filters": { "get": { "description": "Returns endpoint filters for a specific application.", "responses": { "200": { "description": "Endpoint filters retrieved successfully.", "headers": { "ETag": { "description": "Represents the current filters state.\n
The value can be used in `If-Match` and `If-None-Match` headers.\n", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FiltersPageInfo" }, "example": { "totalElements": 2, "content": [ { "id": "79c717d9-eedd-4f71-b9f8-86caf7e309e4", "createdDate": "2017-04-21T12:09:57.848Z", "updatedDate": "2017-04-22T19:45:00.112Z", "name": "app1-1_key1GreaterThanZero", "description": "Some description.", "mongoQuery": { "$and": [ { "application_version_name": "app1-1" }, { "metadata": { "$elemMatch": { "key": "key1", "value": { "$gt": 0 } } } } ] }, "status": "active" }, { "id": "1dc01725-b9d9-41a7-aa28-75a110b89d90", "createdDate": "2017-05-03T05:17:59.789Z", "updatedDate": "2017-06-17T07:18:14.431Z", "description": "Some description.", "mongoQuery": { "metadata": { "$elemMatch": { "key": "key2", "value": 2 } } }, "status": "pending" } ] } } } } }, "security": [ { "oauth_2_0": [ "application:endpoint-filter:read" ] } ], "parameters": [ { "name": "name", "in": "query", "description": "Filter name", "required": false, "schema": { "type": "string" } }, { "name": "offset", "in": "query", "description": "Start index that the server should return data from.", "required": false, "schema": { "type": "integer" }, "example": 0 }, { "name": "limit", "in": "query", "description": "Maximum number of items to return. To get all items limit must be 0.", "required": false, "schema": { "type": "integer", "default": 1000 }, "example": 100 } ] }, "post": { "description": "Creates an endpoint filter in specific application.", "responses": { "201": { "description": "Endpoint filter successfully created.", "headers": { "ETag": { "description": "Represents the current filter state.\n
The value can be used in `If-Match` and `If-None-Match` headers.\n", "schema": { "type": "string" } }, "Location": { "description": "URI in format `{schema}://{host}:{port}/api/v1/applications/{applicationName}/filters/{filterId}`\n", "schema": { "type": "string" } } } }, "400": { "description": "Invalid or missing query", "content": { "application/json": { "schema": { "type": "object" } } } } }, "security": [ { "oauth_2_0": [ "application:endpoint-filter:create" ] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateEndpointFilterRequest" }, "example": { "name": "app1-1_key1GreaterThanZero", "description": "Filters all endpoints with the 'key1' greater than '0'", "mongoQuery": { "$and": [ { "application_version": "app1-1" }, { "metadata": { "$elemMatch": { "key": "key1", "value": { "$gt": 0 } } } } ] } } } } } } }, "/applications/{applicationName}/filters/{filterId}": { "parameters": [ { "name": "applicationName", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Application name", "example": "smart_kettle" }, { "name": "filterId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Endpoint filter ID, unique in scope of application.", "example": "79c717d9-eedd-4f71-b9f8-86caf7e309e4" } ], "patch": { "description": "Updates an endpoint filter.", "responses": { "204": { "description": "Endpoint filter successfully updated." }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "type": "object" } } } }, "412": { "description": "Precondition specified in `If-Match` header failed.\n" } }, "security": [ { "oauth_2_0": [ "application:endpoint-filter:update" ] } ], "parameters": [ { "name": "If-Match", "in": "header", "description": "Makes the request conditional.\n
The server will execute operation only if current `ETag` value matches the specified one.\n
Otherwise, `412 Precondition Failed` status will be returned.\n", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchEndpointFilterRequest" }, "example": { "name": "app1-1_key1GreaterThanZero", "description": "Filters all endpoints with the 'key1' greater than '0'", "mongoQuery": { "$and": [ { "application_version": "app1-1" }, { "metadata": { "$elemMatch": { "key": "key1", "value": { "$gt": 0 } } } } ] } } } } } }, "get": { "description": "Returns an endpoint filter.", "responses": { "200": { "description": "Endpoint filter retrieved successfully.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "id": "79c717d9-eedd-4f71-b9f8-86caf7e309e4", "createdDate": "2017-04-21T12:09:57.848Z", "updatedDate": "2017-04-22T19:45:00.112Z", "name": "app1-1_key1GreaterThanZero", "description": "Some description.", "mongoQuery": { "$and": [ { "application_version_name": "app1-1" }, { "metadata": { "$elemMatch": { "key": "key1", "value": { "$gt": 0 } } } } ] }, "status": "active", "matchedEndpointsCount": 0 } } } } }, "security": [ { "oauth_2_0": [ "application:endpoint-filter:read" ] } ] }, "delete": { "description": "Deletes an endpoint filter.", "responses": { "204": { "description": "Endpoint filter successfully deleted." }, "412": { "description": "Precondition specified in `If-Match` header failed.\n" } }, "security": [ { "oauth_2_0": [ "application:endpoint-filter:delete" ] } ], "parameters": [ { "name": "If-Match", "in": "header", "description": "Makes the request conditional.\n
The server will execute operation only if current `ETag` value matches the specified one.\n
Otherwise, `412 Precondition Failed` status will be returned.\n", "required": false, "schema": { "type": "string" } } ] } }, "/applications/{applicationName}/metadata-keys": { "parameters": [ { "name": "applicationName", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Application name to operate on.", "example": "c4f5gl2d4ks1slmoepa0" } ], "get": { "description": "Returns all endpoint metadata keys set for endpoints in a given application.", "responses": { "200": { "description": "Metadata keys is successfully retrieved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EndpointsMetadataKeys" }, "example": { "smart_kettle_v1": [ "fwVersion", "serial", "powerType" ], "smart_kettle_v2": [ "sensingCapabilities", "description" ] } } } } }, "security": [ { "oauth_2_0": [ "application:endpoints-metadata-keys:read" ] } ] } }, "/relations/link": { "put": { "description": "Creates a directed relation type between endpoints.", "responses": { "204": { "description": "Endpoints are successfully linked." }, "400": { "description": "An error occurred during linking.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "successful": [ { "type": "contains", "from": "aaa6f08f-d839-4089-baca-380e7365953f", "to": "59f52930-7aec-43a3-b8d2-0dd8538afb81" } ], "failed": [ { "type": "contains", "from": "79c717d9-eedd-4f71-b9f8-86caf7e309e4", "to": "34e04cd1-f13d-49ca-adca-a8290c44fb30", "reason": "Relation already exists" } ] } } } } }, "security": [ { "oauth_2_0": [ "endpoint:update" ] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object" }, "example": [ { "type": "contains", "from": "34e04cd1-f13d-49ca-adca-a8290c44fb30", "to": "47243977-4eea-423b-818e-ac67f91106d6" }, { "type": "contains", "from": "aaa6f08f-d839-4089-baca-380e7365953f", "to": "59f52930-7aec-43a3-b8d2-0dd8538afb81" } ] } } } } }, "/relations/unlink": { "put": { "description": "Deletes a directed relation type between endpoints.", "responses": { "204": { "description": "Endpoints are successfully unlinked." }, "400": { "description": "An error occurred during unlinking." } }, "security": [ { "oauth_2_0": [ "endpoint:update" ] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object" }, "example": [ { "type": "contains", "from": "34e04cd1-f13d-49ca-adca-a8290c44fb30", "to": "47243977-4eea-423b-818e-ac67f91106d6" }, { "type": "contains", "from": "aaa6f08f-d839-4089-baca-380e7365953f", "to": "59f52930-7aec-43a3-b8d2-0dd8538afb81" } ] } } } } } }, "components": { "securitySchemes": { "oauth_2_0": { "type": "oauth2", "description": "EPR supports OAuth 2.0 for authenticating all API requests.\n", "flows": { "implicit": { "authorizationUrl": "https://auth.example.com/oauth/authorize", "scopes": {} } } } }, "schemas": { "EndpointMetadata": { "type": "object", "description": "Endpoint metadata consists of multiple key-value pairs (called fields) where keys are strings, and the values are of any JSON type." }, "EndpointRegistrationRelation": { "type": "object", "properties": { "type": { "type": "object", "description": "Relation type.", "enum": [ "contains" ] }, "from": { "type": "string", "description": "Endpoint ID having the outbound direction of relation type coming to the registering endpoint." }, "to": { "type": "string", "description": "Endpoint ID having the inbound direction of relation type coming from the registering endpoint." } }, "required": [ "type" ] }, "EndpointRegistrationRequest": { "type": "object", "properties": { "metadata": { "$ref": "#/components/schemas/EndpointMetadata" }, "endpointToken": { "type": "string", "description": "Endpoint token. Will be auto-generated if not present.\n
\nMust be application-scope unique. Must not contain plus signs (`+`), number signs (`#`), forward slashes (`/`), or periods (`.`).\n", "pattern": "^[^+#/.]+$" }, "endpointId": { "type": "string", "description": "Endpoint ID. Will be auto-generated if not present.\n
\nMust be globally unique. Must contain only URL unreserved characters.\n", "pattern": "^[a-zA-Z0-9._~-]+$" }, "relations": { "type": "array", "items": { "$ref": "#/components/schemas/EndpointRegistrationRelation" }, "description": "Endpoint relation with other endpoints.\nOnly one of the directions - either `to` or `from`, must be specified in each relation entry.\nFor example, registering an endpoint that represents a room, you can specify two entries with the relation type `contains` - inbound from the endpoint representing a building (`from`), and outbound to the endpoint representing a sensor in that room (`to`).\n" }, "resourceGroupIds": { "type": "array", "items": { "type": "string" }, "description": "Resource groups the endpoint will be attached to." } } }, "EndpointRelation": { "type": "object", "properties": { "type": { "type": "string", "description": "Relation type.", "enum": [ "contains" ] }, "from": { "type": "string", "description": "Endpoint ID with the outbound direction of the relation type coming to the endpoint referenced by the `to` key." }, "to": { "type": "string", "description": "Endpoint ID with the inbound direction of the relation type coming from the endpoint referenced by the `from` key." } }, "required": [ "type", "from", "to" ] }, "EndpointRelationWithReason": { "type": "object", "properties": { "type": { "type": "string", "description": "Relation type.", "enum": [ "contains" ] }, "from": { "type": "string", "description": "Endpoint ID with the outbound direction of the relation type coming to the endpoint referenced by the `to` key." }, "to": { "type": "string", "description": "Endpoint ID with the inbound direction of the relation type coming from the endpoint referenced by the `from` key." }, "reason": { "type": "string", "description": "Reason of the relation creation failure." } }, "required": [ "type", "from", "to", "reason" ] }, "RelationCreationStatus": { "type": "object", "properties": { "successful": { "type": "array", "items": { "$ref": "#/components/schemas/EndpointRelation" }, "description": "Successfully handled relations." }, "failed": { "type": "array", "items": { "$ref": "#/components/schemas/EndpointRelationWithReason" }, "description": "Unsuccessfully handled relations with reason description." } }, "required": [ "successful", "failed" ] }, "EndpointRegistrationResponse": { "type": "object", "properties": { "token": { "type": "string", "description": "Endpoint token." }, "status": { "type": "string", "description": "Status of newly provisioned token is always `Inactive`.\n
\nToken status will be automatically changed to `Active` after first successful token validation request.\n", "enum": [ "Inactive" ] }, "relations": { "$ref": "#/components/schemas/RelationCreationStatus" } }, "required": [ "token", "status" ] }, "ApplicationVersionRegistrationRequest": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the application version." } }, "required": [ "name" ] }, "Endpoint": { "type": "object", "properties": { "endpointId": { "type": "string", "description": "Unique identifier of endpoint." }, "createdDate": { "type": "string", "format": "rfc3339", "description": "Endpoint registration data in ISO 8601 format (UTC timezone)." }, "appName": { "type": "string", "description": "Application name that endpoint belongs to." }, "appVersion": { "$ref": "#/components/schemas/ApplicationVersionRegistrationRequest" }, "metadata": { "type": "object" }, "metadataUpdatedDate": { "type": "string", "format": "rfc3339", "description": "Timestamp in ISO 8601 format (UTC timezone) showing when the endpoint metadata was last updated." }, "filters": { "type": "array", "items": { "type": "string" }, "description": "List of filters that matches to the endpoint." }, "poolIds": { "type": "array", "items": { "type": "string" }, "description": "The pool IDs to which endpoint is attached." } }, "required": [ "appName" ] }, "PageInfo": { "type": "object", "properties": { "totalElements": { "type": "integer", "description": "Total number of elements available for retrieval. Current response may return only a part of all available elements." }, "content": { "type": "array", "items": { "$ref": "#/components/schemas/Endpoint" } } } }, "KeyValueFilter": { "type": "object", "properties": { "key": { "type": "string", "description": "Key.\nSupported keys: `endpointId`, `appVersionName`, `appName`, or any endpoint metadata key.\nFor comparison operators (GREATER_THAN, GREATER_THAN_OR_IN, LESS_THAN, LESS_THAN_OR_IN), the following top-level date fields are also supported: `createdDate`, `appVersion.registeredDate`, `metadataUpdatedDate`. \nDate values must be in ISO 8601 format (e.g., `2024-06-20T12:00:00`).\nWhen omitted with `IN_REGEX` operator, searches across endpoint ID, metadata keys, metadata values, and application version name.\n" }, "values": { "type": "array", "items": { "type": "string" }, "description": "Values that the key must be tested against. Not required for NOT_EXISTS operator." }, "operator": { "type": "string", "description": "IN - matches if the key is equal to one of the value.
\nNOT_IN - matches if the key is NOT equal to all the values.
\nIN_REGEX - matches if the key matches one of the regex value. When 'key' is omitted, performs case-insensitive regex search across endpoint ID, metadata keys, metadata values, and application version name.
\nNOT_IN_REGEX - matches if the key does NOT match all the regex values.
\nNOT_EXISTS - matches if the metadata key does not exist on the endpoint.
\nGREATER_THAN - matches if the key value is strictly greater than the specified value.
\nGREATER_THAN_OR_IN - matches if the key value is greater than or equal to the specified value.
\nLESS_THAN - matches if the key value is strictly less than the specified value.
\nLESS_THAN_OR_IN - matches if the key value is less than or equal to the specified value.
\n", "enum": [ "IN", "NOT_IN", "IN_REGEX", "NOT_IN_REGEX", "NOT_EXISTS", "GREATER_THAN", "GREATER_THAN_OR_IN", "LESS_THAN", "LESS_THAN_OR_IN" ] }, "and": { "type": "array", "items": { "type": "object" }, "description": "Nested AND subfilters. All must match, combined with the parent filter condition using AND." }, "or": { "type": "array", "items": { "type": "object" }, "description": "Nested OR subfilters. At least one must match, combined with the parent filter condition using AND." } } }, "MultiFilter": { "type": "object", "properties": { "and": { "type": "array", "items": { "$ref": "#/components/schemas/KeyValueFilter" }, "description": "And." }, "or": { "type": "array", "items": { "type": "object" }, "description": "Or." }, "sort": { "type": "string", "description": "Metadata field to sort by." }, "sortOrder": { "type": "string", "description": "Sort direction.", "enum": [ "asc", "desc" ] }, "offset": { "type": "integer", "description": "Number of results to skip from the beginning. Used for pagination." }, "limit": { "type": "integer", "description": "Maximum number of results to return. Defaults to 100." }, "filterIds": { "type": "array", "items": { "type": "string" }, "description": "EPR filter IDs. Only endpoints matching all specified filters are returned." }, "metadataKeys": { "type": "array", "items": { "type": "string" }, "description": "Only return specified metadata keys in the response.\n
Keys must contain only Latin letters, digits, and underscores.\n" } }, "required": [ "and", "or" ] }, "BatchDeleteRequest": { "type": "object", "properties": { "multiFilter": { "type": "object", "description": "Multi-filter to delete endpoints by." } }, "required": [ "multiFilter" ] }, "EndpointRegistrationItem": { "type": "object", "properties": { "endpointToken": { "type": "string", "description": "Endpoint token.\n
\nMust be application-scope unique. Must not contain plus signs (`+`), number signs (`#`), forward slashes (`/`), or periods (`.`).\n", "pattern": "^[^+#/.]+$" }, "metadata": { "type": "object" } }, "required": [ "endpointToken" ] }, "EndpointBatchRegistrationRequest": { "type": "object", "properties": { "endpoints": { "type": "array", "items": { "$ref": "#/components/schemas/EndpointRegistrationItem" } } } }, "BatchEndpointRegistrationAcceptedResponse": { "type": "object", "properties": { "taskId": { "type": "string", "description": "Batch endpoints registration task ID." } }, "required": [ "taskId" ] }, "ClientErrorResponse": { "type": "object", "properties": { "message": { "type": "string", "description": "Detailed error description." } }, "required": [ "message" ] }, "CreatedBatchEndpointRegistrationItem": { "type": "object", "properties": { "endpointId": { "type": "string", "description": "Endpoint ID." }, "endpointToken": { "type": "string", "description": "Endpoint token." } }, "required": [ "endpointToken" ] }, "FailedBatchEndpointRegistrationItem": { "type": "object", "properties": { "endpointToken": { "type": "string", "description": "Endpoint token." }, "statusReason": { "type": "string", "description": "Cause of failing endpoint registration." } }, "required": [ "endpointToken" ] }, "BatchEndpointRegistrationStatusResponse": { "type": "object", "properties": { "createdCount": { "type": "integer", "description": "Count of endpoints with successful registration." }, "failedCount": { "type": "integer", "description": "Count of endpoints with failed registration." }, "created": { "type": "array", "items": { "$ref": "#/components/schemas/CreatedBatchEndpointRegistrationItem" }, "description": "Array of endpoints with successful registration." }, "failed": { "type": "array", "items": { "$ref": "#/components/schemas/FailedBatchEndpointRegistrationItem" }, "description": "Array of endpoints with failed registration." } }, "required": [ "createdCount", "failedCount", "created", "failed" ] }, "EndpointMetadataValue": {}, "EndpointFilterStatus": { "type": "string", "description": "Endpoint filter status.\n\n" }, "EndpointFilter": { "type": "object", "properties": { "id": { "type": "string", "description": "Endpoint filter ID." }, "name": { "type": "string", "description": "Endpoint filter name, unique in scope of application." }, "description": { "type": "string", "description": "Endpoint filter description." }, "mongoQuery": { "type": "object", "description": "Mongo query used for filtering endpoins by application version and metadata keys." }, "createdDate": { "type": "string", "format": "rfc3339", "description": "Endpoint filter creation timestamp in ISO 8601 format (UTC timezone)." }, "updatedDate": { "type": "string", "format": "rfc3339", "description": "Endpoint filter last update timstamp in ISO 8601 format (UTC timezone)." }, "matchedEndpointsCount": { "type": "integer", "description": "Amount of endpoints that matches the filter criteria." }, "status": { "$ref": "#/components/schemas/EndpointFilterStatus" } }, "required": [ "id", "name", "description", "mongoQuery", "createdDate", "updatedDate", "matchedEndpointsCount" ] }, "FiltersPageInfo": { "type": "object", "properties": { "totalElements": { "type": "integer", "description": "Total number of elements available for retrieval. Current response may return only a part of all available elements." }, "content": { "type": "array", "items": { "$ref": "#/components/schemas/EndpointFilter" } } } }, "CreateEndpointFilterRequest": { "type": "object", "properties": { "name": { "type": "string", "description": "Endpoint filter name, unique in scope of application." }, "description": { "type": "string", "description": "Endpoint filter description." }, "mongoQuery": { "type": "object", "description": "Mongo query used for filtering endpoins by application version and metadata keys." } }, "required": [ "name", "mongoQuery" ] }, "PatchEndpointFilterRequest": { "type": "object", "properties": { "name": { "type": "string", "description": "Endpoint filter name, unique in scope of application." }, "description": { "type": "string", "description": "Endpoint filter description." }, "mongoQuery": { "type": "object", "description": "Mongo query used for filtering endpoins by application version and metadata keys." } } }, "EndpointsMetadataKeys": { "type": "object", "properties": { "appName": { "type": "object", "description": "Application name." } }, "required": [ "appName" ] }, "ApplicationsWithVersions": { "type": "object", "description": "A dictionary that consists of application names with corresponding versions" }, "ApplicationVersions": { "type": "object", "description": "A list of application versions" } } } }