REST API

Endpoint configuration registry 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)

Configurations

Per-endpoint configurations.

/endpoints/{endpointId}/app-versions/{appVersionName} put get delete

put /endpoints/{endpointId}/app-versions/{appVersionName}

Creates or updates (if exists) endpoint configuration for given endpoint identifier and application version.

Secured by oauth_2_0 with scopes:
  • endpoint:update

ECR supports OAuth 2.0 for authenticating all API requests.

URI Parameters

  • endpointId: required(string)

    Identifier of the endpoint to operate on

    Example:

    7d5dda9b-c9f6-427d-91ea-9891a4f62cbb
  • appVersionName: required(string)

    Application version name

    Example:

    smart-kettle-v1

Body

Media type: application/json

Type: any

Example:

{
  "active": true,
  "pushInterval": 5
}

HTTP status code 200

Configuration is successfully upserted.

Headers

  • ETag: required(string)

    Entity tag of the returned configuration.

    Example:

    "33a64df551425fcc55e4d42a148795d9f25f89d4"
    

Body

Media type: application/json

Type: object

Properties

  • configId: required(string)

    Configuration ID

  • config: required(string)

    Configuration payload

  • createdDate: required(datetime)

    Time of configuration creation

  • updatedDate: required(datetime)

    Time of last configuration udpate

Example:

{
  "configId": "231f1aae-a4be-11ea-bb37-0242ac130002",
  "config": "{\"active\": true,\"pushInterval\": 5}",
  "createdDate": "2017-03-17T11:30:02.643Z",
  "updatedDate": "2017-03-17T11:30:02.643Z"
}

HTTP status code 400

Invalid request. E.g. missed required parameters or malformed JSON.

Body

Media type: application/json

Type: object

Properties

  • message: required(string)

    Detailed error description.

HTTP status code 404

Endpoint configuration schema not found but expected. The requirement to the schema existence is configured in the application configuration.

Body

Media type: application/json

Type: object

Properties

  • message: required(string)

    Detailed error description.

HTTP status code 422

Endpoint configuration is unprocessable entity for config schema.

Body

Media type: application/json

Type: object

Properties

  • message: required(string)

    Detailed error description.

HTTP status code 503

Service is configured with invalid endpoint configuration schema.

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.

get /endpoints/{endpointId}/app-versions/{appVersionName}

Returns endpoint configuration details by endpoint identifier and application version.

Secured by oauth_2_0 with scopes:
  • endpoint:read

ECR supports OAuth 2.0 for authenticating all API requests.

URI Parameters

  • endpointId: required(string)

    Identifier of the endpoint to operate on

    Example:

    7d5dda9b-c9f6-427d-91ea-9891a4f62cbb
  • appVersionName: required(string)

    Application version name

    Example:

    smart-kettle-v1

Headers

  • If-None-Match: optional (string)

    Configuration identifier of the last configuration known to the caller. If the current configuration identifier matches one specified in If-None-Match header, no operation is performed and 304 Not modified status code is returned.

    Example:

    "33a64df551425fcc55e4d42a148795d9f25f89d4"
    

HTTP status code 200

Endpoint configuration is successfully retrieved.

Headers

  • ETag: required(string)

    Identifier of the returned configuration.

    Example:

    "33a64df551425fcc55e4d42a148795d9f25f89d4"
    

Body

Media type: application/json

Type: object

Properties

  • configId: required(string)

    Configuration ID

  • config: required(string)

    Configuration payload

  • createdDate: required(datetime)

    Time of configuration creation

  • updatedDate: required(datetime)

    Time of last configuration udpate

Example:

{
  "configId": "231f1aae-a4be-11ea-bb37-0242ac130002",
  "config": "{\"active\": true,\"pushInterval\": 5}",
  "createdDate": "2017-03-17T11:30:02.643Z",
  "updatedDate": "2017-03-17T11:30:02.643Z"
}

HTTP status code 304

Not modified.

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}/app-versions/{appVersionName}

Deletes endpoint configuration by endpoint identifier and application version.

Secured by oauth_2_0 with scopes:
  • endpoint:delete

ECR supports OAuth 2.0 for authenticating all API requests.

URI Parameters

  • endpointId: required(string)

    Identifier of the endpoint to operate on

    Example:

    7d5dda9b-c9f6-427d-91ea-9891a4f62cbb
  • appVersionName: required(string)

    Application version name

    Example:

    smart-kettle-v1

HTTP status code 204

Endpoint configuration was successfully deleted.

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/batch put

put /endpoints/batch

Creates or updates (if exists) configuration for given endpoints in scope of specified application versions.

Secured by oauth_2_0 with scopes:
  • endpoint:update

ECR supports OAuth 2.0 for authenticating all API requests.

Body

Media type: application/json

Type: object

Properties

  • configPayload: required(any)

    Configuration payload

  • endpoints: required(any)

    version-to-endpoints mappings

Example:

{
  "endpoints": {
    "smart-kettle-v1": [
      "7d5dda9b-c9f6-427d-91ea-9891a4f62cbb"
    ]
  },
  "configPayload": {
    "active": true,
    "pushInterval": 5
  }
}

HTTP status code 200

Configurations is successfully upserted.

HTTP status code 400

Invalid request. E.g. missed required parameters or malformed JSON.

Body

Media type: application/json

Type: object

Properties

  • message: required(string)

    Detailed error description.

HTTP status code 404

Endpoint configuration schema not found but expected. The requirement to the schema existence is configured in the application configuration.

Body

Media type: application/json

Type: object

Properties

  • message: required(string)

    Detailed error description.

HTTP status code 422

Endpoint configuration is unprocessable entity for config schema.

Body

Media type: application/json

Type: object

Properties

  • message: required(string)

    Detailed error description.

HTTP status code 503

Service is configured with invalid endpoint configuration schema.

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/filters/{filterId} put

put /endpoints/filters/{filterId}

Creates or updates (if exists) configuration for endpoints that match specified filter.

Secured by oauth_2_0 with scopes:
  • endpoint:update

ECR supports OAuth 2.0 for authenticating all API requests.

URI Parameters

  • filterId: required(string)

    Endpoint filter ID

    Example:

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

Body

Media type: application/json

Type: any

Example:

{
  "active": true,
  "pushInterval": 5
}

HTTP status code 200

Configurations is successfully upserted.

HTTP status code 400

Invalid request. E.g. missed required parameters or malformed JSON.

Body

Media type: application/json

Type: object

Properties

  • message: required(string)

    Detailed error description.

HTTP status code 404

Endpoint configuration schema not found but expected. The requirement to the schema existence is configured in the application configuration.

Body

Media type: application/json

Type: object

Properties

  • message: required(string)

    Detailed error description.

HTTP status code 422

Endpoint configuration is unprocessable entity for config schema.

Body

Media type: application/json

Type: object

Properties

  • message: required(string)

    Detailed error description.

HTTP status code 503

Service is configured with invalid endpoint configuration schema.

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.

Default configurations

Default endpoint configuration for an application version.

/app-versions/{appVersionName} put get delete

put /app-versions/{appVersionName}

Upserts current default configuration for a given application version.

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

ECR supports OAuth 2.0 for authenticating all API requests.

URI Parameters

  • appVersionName: required(string)

    Application version name.

    Example:

    smart-kettle-v1

Headers

  • If-Match: optional (string)

    Configuration identifier of the last configuration known to the caller. If the current configuration identifier does not match one specified in If-Match header, no operation is performed and 412 Precondition failed status code is returned.

    Example:

    "33a64df551425fcc55e4d42a148795d9f25f89d4"
    

Body

Media type: application/json

Type: any

Example:

{
  "active": true,
  "pushInterval": 5
}

HTTP status code 200

Default configuration is successfully upserted.

Headers

  • ETag: required(string)

    Entity tag of the returned configuration.

    Example:

    "33a64df551425fcc55e4d42a148795d9f25f89d4"
    

Body

Media type: application/json

Type: object

Properties

  • configId: required(string)

    Configuration ID

  • config: required(string)

    Configuration payload

  • createdDate: required(datetime)

    Time of configuration creation

  • updatedDate: required(datetime)

    Time of last configuration udpate

Example:

{
  "configId": "231f1aae-a4be-11ea-bb37-0242ac130002",
  "config": "{\"active\": true,\"pushInterval\": 5}",
  "createdDate": "2017-03-17T11:30:02.643Z",
  "updatedDate": "2017-03-17T11:30:02.643Z"
}

HTTP status code 400

Invalid request. E.g. missed required parameters or malformed JSON.

Body

Media type: application/json

Type: object

Properties

  • message: required(string)

    Detailed error description.

HTTP status code 404

Endpoint configuration schema not found but expected. The requirement to the schema existence is configured in the application configuration.

Body

Media type: application/json

Type: object

Properties

  • message: required(string)

    Detailed error description.

HTTP status code 412

Precondition failed. Operation was not performed due to optimistic locking failure.

HTTP status code 422

Endpoint configuration is unprocessable entity for config schema.

Body

Media type: application/json

Type: object

Properties

  • message: required(string)

    Detailed error description.

HTTP status code 503

Service is configured with invalid endpoint configuration schema.

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.

get /app-versions/{appVersionName}

Returns current default configuration.

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

ECR supports OAuth 2.0 for authenticating all API requests.

URI Parameters

  • appVersionName: required(string)

    Application version name.

    Example:

    smart-kettle-v1

Headers

  • If-None-Match: optional (string)

    Configuration identifier of the last configuration known to the caller. If the current configuration identifier matches one specified in If-None-Match header, no operation is performed and 304 Not modified status code is returned.

    Example:

    "33a64df551425fcc55e4d42a148795d9f25f89d4"
    

HTTP status code 200

Default configuration is successfully retrieved.

Headers

  • ETag: required(string)

    Entity tag of the returned configuration.

    Example:

    "33a64df551425fcc55e4d42a148795d9f25f89d4"
    

Body

Media type: application/json

Type: object

Properties

  • configId: required(string)

    Configuration ID

  • config: required(string)

    Configuration payload

  • createdDate: required(datetime)

    Time of configuration creation

  • updatedDate: required(datetime)

    Time of last configuration udpate

Example:

{
  "configId": "231f1aae-a4be-11ea-bb37-0242ac130002",
  "config": "{\"active\": true,\"pushInterval\": 5}",
  "createdDate": "2017-03-17T11:30:02.643Z",
  "updatedDate": "2017-03-17T11:30:02.643Z"
}

HTTP status code 304

Not modified.

HTTP status code 404

Application version not found or user does not have permissions to perform this operation.

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.

delete /app-versions/{appVersionName}

Deletes default configuration by application version.

Secured by oauth_2_0 with scopes:
  • endpoint:delete

ECR supports OAuth 2.0 for authenticating all API requests.

URI Parameters

  • appVersionName: required(string)

    Application version name.

    Example:

    smart-kettle-v1

HTTP status code 204

Default configuration was successfully deleted.

HTTP status code 404

Application version not found or user does not have permissions to perform this operation.

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.

Configuration schemas

Per-version configuration schema.

/app-versions/{appVersionName}/schemas get

get /app-versions/{appVersionName}/schemas

Returns endpoint configuration schema by application version.

Secured by oauth_2_0 with scopes:
  • application:read

ECR supports OAuth 2.0 for authenticating all API requests.

URI Parameters

  • appVersionName: required(string)

    Application version name.

    Example:

    smart_kettle_v1

HTTP status code 200

Returns current endpoint configuration schema (if exist) for the application version.

Body

Media type: application/json

Type: object

Example:

{
  "$id": "https://example.com/test.schema.json",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "Test",
  "type": "object",
  "properties": {
    "testProp": {
      "description": "Description of property",
      "type": "integer",
      "minimum": 0
    }
  }
}

HTTP status code 404

Endpoint configuration schema not found.

Body

Media type: application/json

Type: object

Properties

  • message: required(string)

    Detailed error description.

HTTP status code 503

Service is configured with invalid endpoint configuration schema.

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.

/app-versions/{appVersionName}/schemas/validate put

put /app-versions/{appVersionName}/schemas/validate

Validates endpoint configuration schema by application version name.

Secured by oauth_2_0 with scopes:
  • application:read

ECR supports OAuth 2.0 for authenticating all API requests.

URI Parameters

  • appVersionName: required(string)

    Application version name.

    Example:

    smart_kettle_v1

Body

Media type: application/json

Type: any

Example:

{
  "active": true,
  "pushInterval": 5
}

HTTP status code 200

Configuration passed validation successfully or schema is not expected and is missing.

HTTP status code 400

Invalid request. E.g. missed required parameters or malformed JSON.

Body

Media type: application/json

Type: object

Properties

  • message: required(string)

    Detailed error description.

HTTP status code 404

Endpoint configuration schema not found but expected. The requirement to the schema existence is configured in the application configuration.

Body

Media type: application/json

Type: object

Properties

  • message: required(string)

    Detailed error description.

HTTP status code 422

Endpoint configuration is unprocessable entity for config schema.

Body

Media type: application/json

Type: object

Properties

  • message: required(string)

    Detailed error description.

HTTP status code 503

Service is configured with invalid endpoint configuration schema.

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.

Configuration statuses

Configuration statuses history.

/statuses get

get /statuses

Secured by oauth_2_0 with scopes:
  • endpoint:read

ECR supports OAuth 2.0 for authenticating all API requests.

Query Parameters

  • endpointId: required(string)

    Endpoint identifier. One or many.

    Example:

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

    Application version name.

    Example:

    smart-kettle
  • configId: optional (string)

    Configuration identifier.

    Example:

    8edcc3fa-a0e0-11ea-bb37-0242ac130002

HTTP status code 200

Configuration applicaiton statuses were successfully retrieved.

Body

Media type: application/json

Type: object

Properties

  • content: required(array of ConfigurationStatus)

    Items: ConfigurationStatus

    • configId: required(string)

      Configuration ID

    • endpointId: required(string)

      Endpoint ID

    • appVersionName: required(string)

      Application version name

    • config: optional (string)

      Configuration payload

    • status: required(one of PENDING, DISPATCHED, APPLIED, FAILED)

      Configuration status

    • lastDispatchedDate: optional (datetime)

      Last time configuration was dispatched to endpoint

    • lastConfirmedDate: optional (datetime)

      Last time configuration was confirmed by endpoint

    • confirmationStatusCode: optional (integer)

      Configuration application HTTP status code reported by endpoint

    • confirmationReasonPhrase: optional (integer)

      Configuration application reason phrase reported by endpoint

  • pageable: required(object)
    • sort: required(object)
      • sorted: required(boolean)
      • unsorted: required(boolean)
      • empty: required(boolean)
    • pageNumber: required(integer)
    • pageSize: required(integer)
    • offset: required(integer)
    • paged: required(boolean)
    • unpaged: required(boolean)
  • totalElements: required(integer)
  • totalPages: required(integer)
  • last: required(boolean)
  • sort: required(object)
    • sorted: required(boolean)
    • unsorted: required(boolean)
    • empty: required(boolean)
  • numberOfElements: required(integer)
  • first: required(boolean)
  • size: required(integer)
  • number: required(integer)
  • empty: required(boolean)

Example:

{
  "content": [
    {
      "configId": "4e441d80-7f80-43a7-996f-b89e90da1f3a",
      "endpointId": "bc780a32-aafc-11ea-bb37-0242ac130002",
      "appVersionName": "smart-lamp-v1",
      "config": "{\"speedParams\":{\"Min Speed\":\"42\",\"maxSpeed\":\"70\"},\"speed\":10}",
      "status": "DISPATCHED",
      "lastDispatchedDate": "2020-05-30T18:40:10.150Z",
    },
    {
      "configId": "5cf6cbd1-f776-4ad1-8a7c-fd463673cb61",
      "endpointId": "bc780a32-aafc-11ea-bb37-0242ac130002",
      "appVersionName": "smart-lamp-v1",
      "config": "{\"speedParams\":{\"Min Speed\":\"20\",\"maxSpeed\":\"80\"},\"speed\":40}",
      "status": "APPLIED",
      "lastDispatchedDate": "2020-05-29T18:51:12.350Z",
      "lastConfirmedDate": "2020-05-29T18:51:15.590Z",
      "confirmationStatusCode": 200,
      "confirmationReasonPhrase": "Configuration was successfully applied"
    },
    {
      "configId": "d2c1134c-aafc-11ea-bb37-0242ac130002",
      "endpointId": "bc780a32-aafc-11ea-bb37-0242ac130002",
      "appVersionName": "smart-lamp-v1",
      "config": "{\"speedParams\":{\"Min Speed\":\"30\",\"maxSpeed\":\"90\"},\"speed\":50}",
      "status": "FAILED",
      "lastDispatchedDate": "2020-05-29T18:50:12.350Z",
      "lastConfirmedDate": "2020-05-29T18:51:13.590Z",
      "confirmationStatusCode": 400,
      "confirmationReasonPhrase": "Unsupported max speed"
    }
  ],
  "pageable": {
    "sort": {
      "sorted": false,
      "unsorted": true,
      "empty": true
    },
    "offset": 0,
    "pageNumber": 0,
    "pageSize": 20,
    "paged": true,
    "unpaged": false
  },
  "totalPages": 1,
  "totalElements": 2,
  "last": true,
  "size": 20,
  "number": 0,
  "numberOfElements": 2,
  "sort": {
    "sorted": false,
    "unsorted": true,
    "empty": true
  },
  "first": true,
  "empty": false
}

HTTP status code 404

Configuraion statuses were 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.