REST API

Endpoint Register REST API documentation version v1

{schema}://{host}/api/{version}

  • schema: required (one of http, https - default: http)
  • host: required (string - default: localhost)
  • version: required (v1)

Endpoints

Operations on endpoints, metadata management.

/endpoints post get

post /endpoints

Registers new endpoints within specified application version.

Secured by oauth_2_0 with scopes:
  • application:endpoint:create

EPR supports OAuth 2.0 for authenticating all API requests.

Body

Media type: application/json

Type: object

Properties

  • appVersion: required (object)
    • name: required (string)

      Name of the application version.

  • metadata: (object)

    Endpoint metadata consists of multiple key-value pairs (called fields) where keys are strings, and the values are of any JSON type.

    • endpointToken: (string - pattern: ^[^+#/.]+$)

      Endpoint token. Will be auto-generated if not present.
      Must be application-scope unique. Must not contain plus signs (+), number signs (#), forward slashes (/), or periods (.).

    • endpointId: (string - pattern: ^[a-zA-Z0-9._~-]+$)

      Endpoint ID. Will be auto-generated if not present.
      Must be globally unique. Must contain only URL unreserved characters.

    Example:

    {
      "appVersion": {
        "name":"example_app_v1"
      },
      "metadata": {
        "level": 3,
        "room": 234
      },
      "endpointToken": "02226466-e744-48ac-8f0c-a57fe4e77de4",
      "endpointId": "67b27f9b-c4d1-41dc-b21f-2917b74c467a"
    }
    

    HTTP status code 201

    Endpoint successfully registered within the application version.

    Headers

    • Location: required (string)

      URI in format {schema}://{host}:{port}/api/v1/endpoints/{endpointId}

      Example:

      http://example.com/api/v1/endpoints/79c717d9-eedd-4f71-b9f8-86caf7e309e4

    Body

    Media type: application/json

    Type: object

    Properties

    • token: required (string)

      Endpoint token.

    • status: required (Inactive)

      Status of newly provisioned token is always Inactive.
      Token status will be automatically changed to Active after first successful token validation request.

    Example:

    {
      "token": "02226466-e744-48ac-8f0c-a57fe4e77de4",
      "status": "Inactive"
    }
    

    HTTP status code 400

    Invalid application version name.

    HTTP status code 403

    User does not have permissions to perform this operation.

    Secured by oauth_2_0

    Headers

    • Authorization: (string)

      Used to send a valid OAuth 2 access token. Example: "Authorization: Bearer 'access_token'" where 'access_token' must be replaced by a valid OAuth access token. This header is needed only if API authentication is enabled for the service.

    get /endpoints

    Returns information about endpoints that match query parameters. A response will contain information only about endpoints for which the querying user has appropriate authorization scope.

    Secured by oauth_2_0 with scopes:
    • endpoint:read

    EPR supports OAuth 2.0 for authenticating all API requests.

    Headers

    • If-None-Match: (string)

      Makes the request conditional.
      The server will send the requested endpoint list with 200 status only if current ETag value doesn't match the specified one.
      Otherwise, 304 Not Modified status will be returned.

      Example:

      "33a64df551425fcc55e4d42a148795d9f25f89d4"
      

    Query Parameters

    • endpointId: (string)

      Endpoint identifier, can be one or multiple.

      Example:

      79c717d9-eedd-4f71-b9f8-86caf7e309e4
    • applicationName: (string)

      Filters endpoints by application name.

      Example:

      my-application
    • applicationVersionName: (string)

      Filters endpoints by application version name.

      Example:

      my-application-version
    • offset: (integer)

      Start index that the server should return data from.

      Example:

      0
    • limit: (integer - default: 100)

      Maximum number of items to return. To get all items limit must be 0.

      Example:

      1
    • metadataFilter: (string)

      Filter endpoints by a single metadata key-value pair.
      NOTE Unsafe ASCII characters in the URL must be encoded according to Uniform Resource Locators RFC.

      Example:

      Only endpoints with metadata key areaId equal to router01 are returned:

      {"areaID": "router01"}
      
    • filterId: (string)

      Filter endpoints by matching filter ID(s). If multiple filterId specified, the resultset will contain only endpoints that match all filters. Only querying by the filters with active status is allowed.

    • include: (one of metadata, filters)
      • `metadata` – include `metadata` fields and `metadataUpdatedDate` fields in response.
      • `filters` – include `matching_filters` fields in response.

        • By default, no metadata and filters are returned.

    HTTP status code 200

    Array of endpoint system attributes successfully retrieved.

    Headers

    • ETag: required (string)

      Represents the current endpoint list state.
      The value can be used in If-Match and If-None-Match headers.

      Example:

      "33a64df551425fcc55e4d42a148795d9f25f89d4"
      

    Body

    Media type: application/json

    Type: object

    Properties

    • totalElements: required (integer)

      Total number of elements available for retrieval. Current response may return only a part of all available elements.

    • content: required (array of Endpoint)

      Items: Endpoint

      • endpointId: required (string)

        Unique identifier of endpoint.

      • createdDate: required (datetime)

        Endpoint registration data in ISO 8601 format (UTC timezone).

      • appVersion: required (object)

        Information about endpoint registration wthin specific application version.

        • name: required (string)

          Name of the application version.

        • registeredDate: required (datetime)

          Date when endpoint registration data was created within specific application version.

      • metadata: (object)

        Endpoint metadata consists of multiple key-value pairs (called fields) where keys are strings, and the values are of any JSON type.

        • metadataUpdatedDate: (datetime)

          Timestamp in ISO 8601 format (UTC timezone) showing when the endpoint metadata was last updated.

        • filters: required (array of )

          List of filters that matches to the endpoint.

      Example:

      {
        "totalElements": 1,
        "content": [
          {
            "endpointId": "5a67aa97-1f5c-41eb-a066-8e004157062b",
            "createdDate": "2017-04-20T11:19:57.848Z",
            "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"
            ]
          }
        ]
      }
      

      HTTP status code 304

      Resource(s) not modified.

      HTTP status code 400

      Invalid request.

      Body

      Media type: application/json

      Type: object

      Properties

      • message: required (string)

        Detailed error description.

      Secured by oauth_2_0

      Headers

      • Authorization: (string)

        Used to send a valid OAuth 2 access token. Example: "Authorization: Bearer 'access_token'" where 'access_token' must be replaced by a valid OAuth access token. This header is needed only if API authentication is enabled for the service.

      /endpoints/batch post

      post /endpoints/batch

      Create a task to register a batch of endpoints within a specified application version.

      Secured by oauth_2_0 with scopes:
      • application:endpoint:create

      EPR supports OAuth 2.0 for authenticating all API requests.

      Body

      Media type: application/json

      Type: object

      Properties

      • appVersion: required (object)
        • name: required (string)

          Name of the application version.

      • endpoints: required (array of EndpointRegistrationItem)

        Items: EndpointRegistrationItem

        • endpointToken: required (string - pattern: ^[^+#/.]+$)

          Endpoint token.
          Must be application-scope unique. Must not contain plus signs (+), number signs (#), forward slashes (/), or periods (.).

        • metadata: (object)

          Endpoint metadata consists of multiple key-value pairs (called fields) where keys are strings, and the values are of any JSON type.

        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"
            }
          ]
        }
        

        HTTP status code 202

        Batch endpoint registration task is accepted.

        Body

        Media type: application/json

        Type: object

        Properties

        • taskId: required (string)

          Batch endpoints registration task ID.

        Example:

        {
          "taskId":"79c717d9-eedd-4f71-b9f8-86caf69809e4"
        }

        HTTP status code 400

        Invalid request.

        Body

        Media type: application/json

        Type: object

        Properties

        • message: required (string)

          Detailed error description.

        HTTP status code 403

        User does not have permissions to perform this operation.

        Secured by oauth_2_0

        Headers

        • Authorization: (string)

          Used to send a valid OAuth 2 access token. Example: "Authorization: Bearer 'access_token'" where 'access_token' must be replaced by a valid OAuth access token. This header is needed only if API authentication is enabled for the service.

        /endpoints/batch/status get

        get /endpoints/batch/status

        Returns batch endpoints registration task status.

        Secured by oauth_2_0 with scopes:
        • application:endpoint:create

        EPR supports OAuth 2.0 for authenticating all API requests.

        Query Parameters

        • appName: required (string)

          Application name.

          Example:

          smart-kettle
        • taskId: required (string)

          Batch endpoint registration task ID.

          Example:

          79c717d9-eedd-4f71-b9f8-86caf69809e4

        HTTP status code 200

        Batch endpoint registration task's status is successfully retrieved.

        Body

        Media type: application/json

        Type: object

        Properties

        • createdCount: required (integer)

          Count of endpoints with successful registration.

        • failedCount: required (integer)

          Count of endpoints with failed registration.

        • created: required (array of CreatedBatchEndpointRegistrationItem)

          Array of endpoints with successful registration.

          Items: CreatedBatchEndpointRegistrationItem

          • endpointId: (string)

            Endpoint ID.

          • endpointToken: required (string)

            Endpoint token.

        • failed: required (array of FailedBatchEndpointRegistrationItem)

          Array of endpoints with failed registration.

          Items: FailedBatchEndpointRegistrationItem

          • endpointToken: required (string)

            Endpoint token.

          • statusReason: (string)

            Cause of failing endpoint registration.

        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."
            }
          ]
        }
        

        HTTP status code 400

        Invalid request.

        Body

        Media type: application/json

        Type: object

        Properties

        • message: required (string)

          Detailed error description.

        Secured by oauth_2_0

        Headers

        • Authorization: (string)

          Used to send a valid OAuth 2 access token. Example: "Authorization: Bearer 'access_token'" where 'access_token' must be replaced by a valid OAuth access token. This header is needed only if API authentication is enabled for the service.

        /endpoints/{endpointId} get

        get /endpoints/{endpointId}

        Returns endpoint information.

        Secured by oauth_2_0 with scopes:
        • endpoint:read

        EPR supports OAuth 2.0 for authenticating all API requests.

        URI Parameters

        • endpointId: required (string)

          Identifier of the endpoint to operate on.

          Example:

          79c717d9-eedd-4f71-b9f8-86caf7e309e4

        Headers

        • If-None-Match: (string)

          Makes the request conditional.
          The server will send the requested endpoint with 200 status only if current ETag value doesn't match the specified one.
          Otherwise, 304 Not Modified status will be returned.

          Example:

          "33a64df551425fcc55e4d42a148795d9f25f89d4"
          
        • If-Modified-Since: (datetime)

          Makes the request conditional.
          The server will send the requested endpoint with 200 status only if current Last-Modified value doesn't match the specified one.
          Otherwise, 304 Not Modified status will be returned.

          Example:

          Tue, 05 Sep 2017 08:21:44 GMT

        Query Parameters

        • include: (one of metadata, filters)
          • `metadata` – include `metadata` fields and `metadataUpdatedDate` fields in response.
          • `filters` – include `matching_filters` fields in response.

            • By default, no metadata and filters are returned.

        HTTP status code 200

        Object successfully retrieved.

        Headers

        • ETag: required (string)

          Represents the current endpoint state.
          The value can be used in If-Match and If-None-Match headers.

          Example:

          "33a64df551425fcc55e4d42a148795d9f25f89d4"
          
        • Last-Modified: required (datetime)

          The last modifcation date of endpoint.

          Example:

          Tue, 05 Sep 2017 08:21:44 GMT

        Body

        Media type: application/json

        Type: object

        Properties

        • endpointId: required (string)

          Unique identifier of endpoint.

        • createdDate: required (datetime)

          Endpoint registration data in ISO 8601 format (UTC timezone).

        • appVersion: required (object)

          Information about endpoint registration wthin specific application version.

          • name: required (string)

            Name of the application version.

          • registeredDate: required (datetime)

            Date when endpoint registration data was created within specific application version.

        • metadata: (object)

          Endpoint metadata consists of multiple key-value pairs (called fields) where keys are strings, and the values are of any JSON type.

          • metadataUpdatedDate: (datetime)

            Timestamp in ISO 8601 format (UTC timezone) showing when the endpoint metadata was last updated.

          • filters: required (array of )

            List of filters that matches to the endpoint.

          Example:

          {
            "endpointId": "69c4c970-94ce-4608-bf36-736d16fdab82",
            "createdDate": "2017-04-20T11:19:57.848Z",
            "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"
            ]
          }
          

          HTTP status code 304

          Resource(s) not modified.

          HTTP status code 400

          Invalid include query parameter.

          Body

          Media type: application/json

          Type: object

          Properties

          • message: required (string)

            Detailed error description.

          HTTP status code 404

          Endpoint not found or querying user is not authorized for it.

          Secured by oauth_2_0

          Headers

          • Authorization: (string)

            Used to send a valid OAuth 2 access token. Example: "Authorization: Bearer 'access_token'" where 'access_token' must be replaced by a valid OAuth access token. This header is needed only if API authentication is enabled for the service.

          /endpoints/{endpointId}/app-version get put

          get /endpoints/{endpointId}/app-version

          Returns endpoint registration data within application version.

          Secured by oauth_2_0 with scopes:
          • endpoint:read

          EPR supports OAuth 2.0 for authenticating all API requests.

          URI Parameters

          • endpointId: required (string)

            Identifier of the endpoint to operate on.

            Example:

            79c717d9-eedd-4f71-b9f8-86caf7e309e4

          HTTP status code 200

          Endpoint registration data retrieved successfully.

          Body

          Media type: application/json

          Type: object

          Properties

          • name: required (string)

            Name of the application version.

          • registeredDate: required (datetime)

            Date when endpoint registration data was created within specific application version.

          Example:

          {
            "name": "example_app_v1",
            "registeredDate": "2017-04-20T11:19:57.848Z"
          }
          

          HTTP status code 404

          Endpoint not found or querying user is not authorized for it.

          Secured by oauth_2_0

          Headers

          • Authorization: (string)

            Used to send a valid OAuth 2 access token. Example: "Authorization: Bearer 'access_token'" where 'access_token' must be replaced by a valid OAuth access token. This header is needed only if API authentication is enabled for the service.

          put /endpoints/{endpointId}/app-version

          Updates endpoint registration data with the application version.

          Secured by oauth_2_0 with scopes:
          • endpoint:update

          EPR supports OAuth 2.0 for authenticating all API requests.

          URI Parameters

          • endpointId: required (string)

            Identifier of the endpoint to operate on.

            Example:

            79c717d9-eedd-4f71-b9f8-86caf7e309e4

          Body

          Media type: application/json

          Type: object

          Properties

          • name: required (string)

            Name of the application version.

          Example:

          {
            "name":"example_app_v2"
          }
          

          HTTP status code 204

          Endpoint registration data updated successfully.

          HTTP status code 400

          Invalid application version name.

          Body

          Media type: application/json

          Type: object

          Properties

          • message: required (string)

            Detailed error description.

          HTTP status code 404

          Endpoint not found or querying user is not authorized for it.

          Secured by oauth_2_0

          Headers

          • Authorization: (string)

            Used to send a valid OAuth 2 access token. Example: "Authorization: Bearer 'access_token'" where 'access_token' must be replaced by a valid OAuth access token. This header is needed only if API authentication is enabled for the service.

          /endpoints/{endpointId}/metadata get put patch

          get /endpoints/{endpointId}/metadata

          Returns all metadata or requested metadata keys (must be a non-empty string containing Latin letters, digits, and underscores only) for a specific endpoint.

          Secured by oauth_2_0 with scopes:
          • endpoint:read

          EPR supports OAuth 2.0 for authenticating all API requests.

          URI Parameters

          • endpointId: required (string)

            Identifier of the endpoint to operate on.

            Example:

            79c717d9-eedd-4f71-b9f8-86caf7e309e4

          Headers

          • If-None-Match: (string)

            Makes the request conditional.
            The server will send the requested endpoint's metadata with 200 status only if current ETag value doesn't match the specified one.
            Otherwise, 304 Not Modified status will be returned.

            Example:

            "33a64df551425fcc55e4d42a148795d9f25f89d4"
            
          • If-Modified-Since: (datetime)

            Makes the request conditional.
            The server will send the requested endpoint's metadata with 200 status only if current Last-Modified value doesn't match the specified one.
            Otherwise, 304 Not Modified status will be returned.

            Example:

            Tue, 05 Sep 2017 08:21:44 GMT

          Query Parameters

          • include: (string)

            Only fields that match any of the include parameters are returned.
            If not specified, all fields are returned.

            Example:

            /endpoints/{endpointId}/metadata?include=key1&include=key2

          HTTP status code 200

          Endpoint metadata of the specified endpoint.

          Headers

          • ETag: required (string)

            Represents the current endpoint's metadata state.
            The value can be used in If-Match and If-None-Match headers.

            Example:

            "33a64df551425fcc55e4d42a148795d9f25f89d4"
            
          • Last-Modified: required (datetime)

            The last modifcation date of endpoint's metadata.

            Example:

            Tue, 05 Sep 2017 08:21:44 GMT

          Body

          Media type: application/json

          Type: object

          Example:

          {
            "OS":{
              "type":"Linux",
              "version":"4.10.6"
            },
            "tag":{
              "id":"1"
            },
            "anyJsonType":[
              11
            ]
          }
          

          HTTP status code 304

          Resource(s) not modified.

          HTTP status code 400

          Metadata keys are not valid.

          HTTP status code 404

          Endpoint not found or querying user is not authorized for it.

          Secured by oauth_2_0

          Headers

          • Authorization: (string)

            Used to send a valid OAuth 2 access token. Example: "Authorization: Bearer 'access_token'" where 'access_token' must be replaced by a valid OAuth access token. This header is needed only if API authentication is enabled for the service.

          put /endpoints/{endpointId}/metadata

          Updates an endpoint metadata.
          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.

          Secured by oauth_2_0 with scopes:
          • endpoint:update

          EPR supports OAuth 2.0 for authenticating all API requests.

          URI Parameters

          • endpointId: required (string)

            Identifier of the endpoint to operate on.

            Example:

            79c717d9-eedd-4f71-b9f8-86caf7e309e4

          Headers

          • If-Match: (string)

            Makes the request conditional.
            The server will execute operation only if current ETag value matches the specified one.
            Otherwise, 412 Precondition Failed status will be returned.

            Example:

            "33a64df551425fcc55e4d42a148795d9f25f89d4"
            
          • If-Unmodified-Since: (datetime)

            Makes the request conditional.
            The server will execute operation only if current Last-Modified value matches the specified one.
            Otherwise, 412 Precondition Failed status will be returned.

            Example:

            Tue, 05 Sep 2017 08:21:44 GMT

          Body

          Media type: application/json

          Type: object

          Example:

          {
            "OS":{
              "type":"Linux",
              "version":"4.10.6"
            },
            "tag":{
              "id":"1"
            },
            "anyJsonType":[
              11
            ]
          }
          

          HTTP status code 204

          Endpoint metadata successfully updated.

          HTTP status code 400

          Payload is not a JSON object or metadata keys are not valid.

          HTTP status code 404

          Endpoint not found or querying user is not authorized for it.

          HTTP status code 412

          At least one of the preconditions specified in If-Match or If-Unmodified-Since headers failed.

          Secured by oauth_2_0

          Headers

          • Authorization: (string)

            Used to send a valid OAuth 2 access token. Example: "Authorization: Bearer 'access_token'" where 'access_token' must be replaced by a valid OAuth access token. This header is needed only if API authentication is enabled for the service.

          patch /endpoints/{endpointId}/metadata

          Applies JSON Patch to the endpoint metadata. If no metadata exists, it is created. Metadata keys must be non-empty strings containing Latin letters, digits, and underscores only.

          Secured by oauth_2_0 with scopes:
          • endpoint:update

          EPR supports OAuth 2.0 for authenticating all API requests.

          URI Parameters

          • endpointId: required (string)

            Identifier of the endpoint to operate on.

            Example:

            79c717d9-eedd-4f71-b9f8-86caf7e309e4

          Headers

          • If-Match: (string)

            Makes the request conditional.
            The server will execute operation only if current ETag value matches the specified one.
            Otherwise, 412 Precondition Failed status will be returned.

            Example:

            "33a64df551425fcc55e4d42a148795d9f25f89d4"
            
          • If-Unmodified-Since: (datetime)

            Makes the request conditional.
            The server will execute operation only if current Last-Modified value matches the specified one.
            Otherwise, 412 Precondition Failed status will be returned.

            Example:

            Tue, 05 Sep 2017 08:21:44 GMT

          Body

          Media type: application/json-patch+json

          Type: array

          Example:

          [
            { "op": "add", "path": "/location", "value": {"city":"Kiev", "street":"Nyzhnoiurkivska"} },
            { "op": "remove", "path": "/anyJsonType/0"},
            { "op": "move", "from": "/OS", "path": "/tag" }
          ]

          HTTP status code 200

          Endpoint metadata successfully patched.

          Body

          Media type: application/json

          Type: object

          Example:

          {
            "OS":{
              "type":"Linux",
              "version":"4.10.6"
            },
            "tag":{
              "id":"1"
            },
            "anyJsonType":[
              11
            ]
          }
          

          HTTP status code 400

          Invalid JSON Patch format or metadata keys are not valid.

          HTTP status code 404

          Endpoint not found or querying user is not authorized for it.

          HTTP status code 412

          At least one of the preconditions specified in If-Match or If-Unmodified-Since headers failed.

          Secured by oauth_2_0

          Headers

          • Authorization: (string)

            Used to send a valid OAuth 2 access token. Example: "Authorization: Bearer 'access_token'" where 'access_token' must be replaced by a valid OAuth access token. This header is needed only if API authentication is enabled for the service.

          /endpoints/{endpointId}/metadata/{metadataKey} get put delete

          get /endpoints/{endpointId}/metadata/{metadataKey}

          Returns metadata value for the specified key.

          Secured by oauth_2_0 with scopes:
          • endpoint:read

          EPR supports OAuth 2.0 for authenticating all API requests.

          URI Parameters

          • endpointId: required (string)

            Identifier of the endpoint to operate on.

            Example:

            79c717d9-eedd-4f71-b9f8-86caf7e309e4
          • metadataKey: required (string)

            Metadata key must be a non-empty string containing Latin letters, digits, and underscores only.

            Example:

            OS

          HTTP status code 200

          Metadata value for the specified key.

          Body

          Media type: application/json

          Type: any

          Examples:

          A JSON object.:

          {
            "kernel": "Linux",
            "version": 5
          }

          A string value.:

          "value1"

          A boolean value.:

          false

          A JSON array value.:

          [
            1,
            2.3,
            4
          ]

          A number value.:

          2

          HTTP status code 400

          Bad request.

          HTTP status code 404

          Endpoint or metadata key not found or user is not authorized for the endpoint.

          Body

          Media type: application/json

          Type: object

          Properties

          • message: required (string)

            Detailed error description.

          Examples:

          Endpoint not found.:

          {
            "message": "No endpoint found."
          }

          Metadata key not found.:

          {
            "message": "No metadata key found."
          }

          Secured by oauth_2_0

          Headers

          • Authorization: (string)

            Used to send a valid OAuth 2 access token. Example: "Authorization: Bearer 'access_token'" where 'access_token' must be replaced by a valid OAuth access token. This header is needed only if API authentication is enabled for the service.

          put /endpoints/{endpointId}/metadata/{metadataKey}

          Creates and updates single endpoint metadata field.

          Secured by oauth_2_0 with scopes:
          • endpoint:update

          EPR supports OAuth 2.0 for authenticating all API requests.

          URI Parameters

          • endpointId: required (string)

            Identifier of the endpoint to operate on.

            Example:

            79c717d9-eedd-4f71-b9f8-86caf7e309e4
          • metadataKey: required (string)

            Metadata key must be a non-empty string containing Latin letters, digits, and underscores only.

            Example:

            OS

          Body

          Media type: application/json

          Type: any

          Examples:

          A JSON object.:

          {
            "kernel": "Linux",
            "version": 5
          }

          A string value.:

          "value1"

          A boolean value.:

          false

          A JSON array value.:

          [
            1,
            2.3,
            4
          ]

          A number value.:

          2

          HTTP status code 200

          Single endpoint metadata key-value pair successfully updated.

          Body

          Media type: application/json

          Type: any

          Examples:

          A JSON object.:

          {
            "kernel": "Linux",
            "version": 5
          }

          A string value.:

          "value1"

          A boolean value.:

          false

          A JSON array value.:

          [
            1,
            2.3,
            4
          ]

          A number value.:

          2

          HTTP status code 201

          Single endpoint metadata key-value pair successfully created.

          Headers

          • Location: required (string)

            Location of the newly created endpoint metadata key-value pair. The format is as follows: {schema}://{host}:{port}/api/{version}/endpoints/{endpointId}/metadata/{metadataKey}

            Example:

            http://example.com/api/v1/endpoints/79c717d9-eedd-4f71-b9f8-86caf7e309e4/metadata/OS

          Body

          Media type: application/json

          Type: any

          Examples:

          A JSON object.:

          {
            "kernel": "Linux",
            "version": 5
          }

          A string value.:

          "value1"

          A boolean value.:

          false

          A JSON array value.:

          [
            1,
            2.3,
            4
          ]

          A number value.:

          2

          HTTP status code 400

          Invalid JSON value or metadata key is not valid.

          HTTP status code 404

          Endpoint not found or querying user is not authorized for it.

          Secured by oauth_2_0

          Headers

          • Authorization: (string)

            Used to send a valid OAuth 2 access token. Example: "Authorization: Bearer 'access_token'" where 'access_token' must be replaced by a valid OAuth access token. This header is needed only if API authentication is enabled for the service.

          delete /endpoints/{endpointId}/metadata/{metadataKey}

          Deletes single endpoint metadata field for a specific endpoint.

          Secured by oauth_2_0 with scopes:
          • endpoint:update

          EPR supports OAuth 2.0 for authenticating all API requests.

          URI Parameters

          • endpointId: required (string)

            Identifier of the endpoint to operate on.

            Example:

            79c717d9-eedd-4f71-b9f8-86caf7e309e4
          • metadataKey: required (string)

            Metadata key must be a non-empty string containing Latin letters, digits, and underscores only.

            Example:

            OS

          HTTP status code 204

          Endpoint metadata key successfully deleted.

          HTTP status code 400

          Invalid metadata key.

          HTTP status code 404

          Endpoint or metadata key not found or user is not authorized for the endpoint.

          Body

          Media type: application/json

          Type: object

          Properties

          • message: required (string)

            Detailed error description.

          Examples:

          Endpoint not found.:

          {
            "message": "No endpoint found."
          }

          Metadata key not found.:

          {
            "message": "No metadata key found."
          }

          Secured by oauth_2_0

          Headers

          • Authorization: (string)

            Used to send a valid OAuth 2 access token. Example: "Authorization: Bearer 'access_token'" where 'access_token' must be replaced by a valid OAuth access token. This header is needed only if API authentication is enabled for the service.

          /endpoints/{endpointId}/metadata-keys get

          get /endpoints/{endpointId}/metadata-keys

          Returns all endpoint metadata keys for the specified endpoint.

          Secured by oauth_2_0 with scopes:
          • endpoint:read

          EPR supports OAuth 2.0 for authenticating all API requests.

          URI Parameters

          • endpointId: required (string)

            Identifier of the endpoint to operate on.

            Example:

            79c717d9-eedd-4f71-b9f8-86caf7e309e4

          Headers

          • If-None-Match: (string)

            Makes the request conditional.
            The server will send the requested metadata keys with 200 status only if current ETag value doesn't match the specified one.
            Otherwise, 304 Not Modified status will be returned.

            Example:

            "33a64df551425fcc55e4d42a148795d9f25f89d4"
            

          HTTP status code 200

          Array that contains all metadata fields.

          Headers

          • ETag: required (string)

            Represents the current metadata keys state.
            The value can be used in If-Match and If-None-Match headers.

            Example:

            "33a64df551425fcc55e4d42a148795d9f25f89d4"
            

          Body

          Media type: application/json

          Type: array of string

          Example:

          [
            "OS",
            "country",
            "level"
          ]

          HTTP status code 304

          Resource(s) not modified.

          HTTP status code 404

          Endpoint not found or querying user is not authorized for it.

          Secured by oauth_2_0

          Headers

          • Authorization: (string)

            Used to send a valid OAuth 2 access token. Example: "Authorization: Bearer 'access_token'" where 'access_token' must be replaced by a valid OAuth access token. This header is needed only if API authentication is enabled for the service.

          Filters

          Operations on endpoint filters.

          /applications/{applicationName}/filters get post

          get /applications/{applicationName}/filters

          Returns endpoint filters for a specific application.

          Secured by oauth_2_0 with scopes:
          • application:endpoint-filter:read

          EPR supports OAuth 2.0 for authenticating all API requests.

          URI Parameters

          • applicationName: required (string)

            Application name

            Example:

            smart_kettle

          Headers

          • If-None-Match: (string)

            Makes the request conditional.
            The server will send the requested endpoint's filters with 200 status only if current ETag value doesn't match the specified one.
            Otherwise, 304 Not Modified status will be returned.

            Example:

            "33a64df551425fcc55e4d42a148795d9f25f89d4"
            

          Query Parameters

          • name: (string)

            Filter name

          • offset: (integer)

            Start index that the server should return data from.

            Example:

            0
          • limit: (integer - default: 1000)

            Maximum number of items to return. To get all items limit must be 0.

            Example:

            100

          HTTP status code 200

          Endpoint filters retrieved successfully.

          Headers

          • ETag: required (string)

            Represents the current filters state.
            The value can be used in If-Match and If-None-Match headers.

            Example:

            "33a64df551425fcc55e4d42a148795d9f25f89d4"
            

          Body

          Media type: application/json

          Type: object

          Properties

          • totalElements: required (integer)

            Total number of elements available for retrieval. Current response may return only a part of all available elements.

          • content: required (array of EndpointFilter)

            Items: EndpointFilter

            • id: required (string)

              Endpoint filter ID.

            • name: required (string)

              Endpoint filter name, unique in scope of application.

            • description: required (string)

              Endpoint filter description.

            • mongoQuery: required (object)

              Mongo query used for filtering endpoins by application version and metadata keys.

              • createdDate: required (datetime)

                Endpoint filter creation timestamp in ISO 8601 format (UTC timezone).

              • updatedDate: required (datetime)

                Endpoint filter last update timstamp in ISO 8601 format (UTC timezone).

              • matchedEndpointsCount: required (integer)

                Amount of endpoints that matches the filter criteria.

              • status: required (one of pending, active)

                Endpoint filter status.

                • `pending` - endpoint filter matching to endpoints is in progress
                • `active` - endpoint filter matching to endpoints is finished

            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"
                }
              ]
            }
            

            HTTP status code 304

            Resource(s) not modified.

            HTTP status code 404

            Resource not found.

            Body

            Media type: application/json

            Type: object

            Properties

            • message: required (string)

              Detailed error description.

            Secured by oauth_2_0

            Headers

            • Authorization: (string)

              Used to send a valid OAuth 2 access token. Example: "Authorization: Bearer 'access_token'" where 'access_token' must be replaced by a valid OAuth access token. This header is needed only if API authentication is enabled for the service.

            post /applications/{applicationName}/filters

            Creates an endpoint filter in specific application.

            Secured by oauth_2_0 with scopes:
            • application:endpoint-filter:create

            EPR supports OAuth 2.0 for authenticating all API requests.

            URI Parameters

            • applicationName: required (string)

              Application name

              Example:

              smart_kettle

            Body

            Media type: application/json

            Type: object

            Properties

            • name: required (string)

              Endpoint filter name, unique in scope of application.

            • description: (string)

              Endpoint filter description.

            • mongoQuery: required (object)

              Mongo query used for filtering endpoins by application version and metadata keys.

              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
                          }
                        }
                      }
                    }
                  ]
                }
              }
              

              HTTP status code 201

              Endpoint filter successfully created.

              Headers

              • ETag: required (string)

                Represents the current filter state.
                The value can be used in If-Match and If-None-Match headers.

                Example:

                "33a64df551425fcc55e4d42a148795d9f25f89d4"
                
              • Location: required (string)

                URI in format {schema}://{host}:{port}/api/v1/applications/{applicationName}/filters/{filterId}

                Example:

                http://example.com/api/v1/applications/smart-kettle/filters/79c717d9-eedd-4f71-b9f8-86caf7e309e4

              HTTP status code 400

              Invalid or missing query

              Body

              Media type: application/json

              Type: object

              Properties

              • message: required (string)

                Detailed error description.

              HTTP status code 404

              Resource not found.

              Body

              Media type: application/json

              Type: object

              Properties

              • message: required (string)

                Detailed error description.

              HTTP status code 409

              Endpoint filter with such name already exists in specified application.

              Body

              Media type: application/json

              Type: object

              Properties

              • message: required (string)

                Detailed error description.

              Example:

              {
                "message": "Endpoint filter with such name already exists in specified application."
              }

              Secured by oauth_2_0

              Headers

              • Authorization: (string)

                Used to send a valid OAuth 2 access token. Example: "Authorization: Bearer 'access_token'" where 'access_token' must be replaced by a valid OAuth access token. This header is needed only if API authentication is enabled for the service.

              /applications/{applicationName}/filters/{filterId} patch get delete

              patch /applications/{applicationName}/filters/{filterId}

              Updates an endpoint filter.

              Secured by oauth_2_0 with scopes:
              • application:endpoint-filter:update

              EPR supports OAuth 2.0 for authenticating all API requests.

              URI Parameters

              • applicationName: required (string)

                Application name

                Example:

                smart_kettle
              • filterId: required (string)

                Endpoint filter ID, unique in scope of application.

                Example:

                79c717d9-eedd-4f71-b9f8-86caf7e309e4

              Headers

              • If-Match: (string)

                Makes the request conditional.
                The server will execute operation only if current ETag value matches the specified one.
                Otherwise, 412 Precondition Failed status will be returned.

                Example:

                "33a64df551425fcc55e4d42a148795d9f25f89d4"
                

              Body

              Media type: application/json

              Type: object

              Properties

              • name: (string)

                Endpoint filter name, unique in scope of application.

              • description: (string)

                Endpoint filter description.

              • mongoQuery: (object)

                Mongo query used for filtering endpoins by application version and metadata keys.

                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
                            }
                          }
                        }
                      }
                    ]
                  }
                }
                

                HTTP status code 204

                Endpoint filter successfully updated.

                HTTP status code 400

                Invalid request.

                Body

                Media type: application/json

                Type: object

                Properties

                • message: required (string)

                  Detailed error description.

                HTTP status code 404

                Application or endpoint filter not found.

                Body

                Media type: application/json

                Type: object

                Properties

                • message: required (string)

                  Detailed error description.

                Examples:

                Application is not found.:

                {
                  "message": "Unknown application name!"
                }

                Endpoint filter not found.:

                {
                  "message": "Endpoint filter not found."
                }

                HTTP status code 409

                Endpoint filter with such name already exists in specified application.

                Body

                Media type: application/json

                Type: object

                Properties

                • message: required (string)

                  Detailed error description.

                Example:

                {
                  "message": "Endpoint filter with such name already exists in specified application."
                }

                HTTP status code 412

                Precondition specified in If-Match header failed.

                Secured by oauth_2_0

                Headers

                • Authorization: (string)

                  Used to send a valid OAuth 2 access token. Example: "Authorization: Bearer 'access_token'" where 'access_token' must be replaced by a valid OAuth access token. This header is needed only if API authentication is enabled for the service.

                get /applications/{applicationName}/filters/{filterId}

                Returns an endpoint filter.

                Secured by oauth_2_0 with scopes:
                • application:endpoint-filter:read

                EPR supports OAuth 2.0 for authenticating all API requests.

                URI Parameters

                • applicationName: required (string)

                  Application name

                  Example:

                  smart_kettle
                • filterId: required (string)

                  Endpoint filter ID, unique in scope of application.

                  Example:

                  79c717d9-eedd-4f71-b9f8-86caf7e309e4

                Headers

                • If-None-Match: (string)

                  Makes the request conditional.
                  The server will send the requested filter with 200 status only if current ETag value doesn't match the specified one.
                  Otherwise, 304 Not Modified status will be returned.

                  Example:

                  "33a64df551425fcc55e4d42a148795d9f25f89d4"
                  

                HTTP status code 200

                Endpoint filter retrieved successfully.

                Headers

                • ETag: required (string)

                  Represents the current filter state.
                  The value can be used in If-Match and If-None-Match headers.

                  Example:

                  "33a64df551425fcc55e4d42a148795d9f25f89d4"
                  

                Body

                Media type: application/json

                Type: object

                Properties

                • id: required (string)

                  Endpoint filter ID.

                • name: required (string)

                  Endpoint filter name, unique in scope of application.

                • description: required (string)

                  Endpoint filter description.

                • mongoQuery: required (object)

                  Mongo query used for filtering endpoins by application version and metadata keys.

                  • createdDate: required (datetime)

                    Endpoint filter creation timestamp in ISO 8601 format (UTC timezone).

                  • updatedDate: required (datetime)

                    Endpoint filter last update timstamp in ISO 8601 format (UTC timezone).

                  • matchedEndpointsCount: required (integer)

                    Amount of endpoints that matches the filter criteria.

                  • status: required (one of pending, active)

                    Endpoint filter status.

                    • `pending` - endpoint filter matching to endpoints is in progress
                    • `active` - endpoint filter matching to endpoints is finished

                  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
                  }
                  

                  HTTP status code 304

                  Resource(s) not modified.

                  HTTP status code 404

                  Application or endpoint filter not found.

                  Body

                  Media type: application/json

                  Type: object

                  Properties

                  • message: required (string)

                    Detailed error description.

                  Examples:

                  Application is not found.:

                  {
                    "message": "Unknown application name!"
                  }

                  Endpoint filter not found.:

                  {
                    "message": "Endpoint filter not found."
                  }

                  Secured by oauth_2_0

                  Headers

                  • Authorization: (string)

                    Used to send a valid OAuth 2 access token. Example: "Authorization: Bearer 'access_token'" where 'access_token' must be replaced by a valid OAuth access token. This header is needed only if API authentication is enabled for the service.

                  delete /applications/{applicationName}/filters/{filterId}

                  Deletes an endpoint filter.

                  Secured by oauth_2_0 with scopes:
                  • application:endpoint-filter:delete

                  EPR supports OAuth 2.0 for authenticating all API requests.

                  URI Parameters

                  • applicationName: required (string)

                    Application name

                    Example:

                    smart_kettle
                  • filterId: required (string)

                    Endpoint filter ID, unique in scope of application.

                    Example:

                    79c717d9-eedd-4f71-b9f8-86caf7e309e4

                  Headers

                  • If-Match: (string)

                    Makes the request conditional.
                    The server will execute operation only if current ETag value matches the specified one.
                    Otherwise, 412 Precondition Failed status will be returned.

                    Example:

                    "33a64df551425fcc55e4d42a148795d9f25f89d4"
                    

                  HTTP status code 204

                  Endpoint filter successfully deleted.

                  HTTP status code 404

                  Application or endpoint filter not found.

                  Body

                  Media type: application/json

                  Type: object

                  Properties

                  • message: required (string)

                    Detailed error description.

                  Examples:

                  Application is not found.:

                  {
                    "message": "Unknown application name!"
                  }

                  Endpoint filter not found.:

                  {
                    "message": "Endpoint filter not found."
                  }

                  HTTP status code 412

                  Precondition specified in If-Match header failed.

                  Secured by oauth_2_0

                  Headers

                  • Authorization: (string)

                    Used to send a valid OAuth 2 access token. Example: "Authorization: Bearer 'access_token'" where 'access_token' must be replaced by a valid OAuth access token. This header is needed only if API authentication is enabled for the service.

                  Applications

                  Operations on applications.

                  /applications/{applicationName}/metadata-keys get

                  get /applications/{applicationName}/metadata-keys

                  Returns all endpoint metadata keys set for endpoints in a given application.

                  Secured by oauth_2_0 with scopes:
                  • application:endpoints-metadata-keys:read

                  EPR supports OAuth 2.0 for authenticating all API requests.

                  URI Parameters

                  • applicationName: required (string)

                  HTTP status code 200

                  Metadata keys is successfully retrieved.

                  Body

                  Media type: application/json

                  Type: object

                  Properties

                  • appName: required (object)

                    Application name.

                    • appVersionName: required (array of )

                      Application version name.

                  Example:

                  {
                    "smart_kettle_v1": [
                      "fwVersion",
                      "serial",
                      "powerType"
                    ],
                    "smart_kettle_v2": [
                      "sensingCapabilities",
                      "description"
                    ]
                  }
                  

                  HTTP status code 404

                  Given application doesn't exist or user is not authorized for it

                  Body

                  Media type: application/json

                  Type: object

                  Properties

                  • message: required (string)

                    Detailed error description.

                  Secured by oauth_2_0

                  Headers

                  • Authorization: (string)

                    Used to send a valid OAuth 2 access token. Example: "Authorization: Bearer 'access_token'" where 'access_token' must be replaced by a valid OAuth access token. This header is needed only if API authentication is enabled for the service.