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: optional (object)

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

    • endpointToken: optional (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: optional (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: optional (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: optional (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: optional (string)

      Endpoint identifier, can be one or multiple.

      Example:

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

      Filters endpoints by application name.

      Example:

      my-application
    • applicationVersionName: optional (string)

      Filters endpoints by application version name.

      Example:

      my-application-version
    • offset: optional (integer)

      Start index that the server should return data from.

      Example:

      0
    • limit: optional (integer - default: 100)

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

      Example:

      1
    • metadataFilter: optional (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: optional (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: optional (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: optional (object)

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

        • metadataUpdatedDate: optional (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: optional (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: optional (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: optional (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: optional (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: optional (object)

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

        • metadataUpdatedDate: optional (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: optional (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: optional (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: optional (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: optional (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: optional (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: optional (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: optional (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: optional (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: optional (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: optional (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: optional (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: optional (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: optional (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: optional (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: optional (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: optional (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: optional (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: optional (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: optional (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: optional (string)

          Filter name

        • offset: optional (integer)

          Start index that the server should return data from.

          Example:

          0
        • limit: optional (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: optional (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: optional (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: optional (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: optional (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: optional (string)

              Endpoint filter name, unique in scope of application.

            • description: optional (string)

              Endpoint filter description.

            • mongoQuery: optional (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: optional (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: optional (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: optional (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: optional (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: optional (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: optional (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.