REST API

Binary data Collection Extension service 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)

Data upload

API for uploading binary data blobs from connected endpoints.

/binary-data post

post /binary-data

Accepts a binary data blob from an endpoint.

Secured by X-Auth-Token

BCX requires X-Auth-Token for authenticating upload API requests. The token must be retrieved in advance by endpoint from the bcx extension service using the regular communication channel.

Query Parameters

  • name: optional (string)

    Arbitrary data blob name to be stored as an attribute.

Body

Media type: application/octet-stream

Type: byte array

HTTP status code 201

Binary data blob successfully uploaded.

Headers

  • Location: required(string)

    URI in format {schema}://{host}:{port}/applications/{appName}/endpoints/{endpointID}/binary-data/{blobId}

    Example:

    http://example.com/api/v1/applications/bqa46oeg10l0thoh4m7g/endpoints/2ebaf0ab-76f3-4211-a27f-af310be8987f/binary-data/gdc35eeh31g0sath8a3c

HTTP status code 403

Operation is not authorized: missing, expired, or invalid auth token.

Secured by X-Auth-Token

Headers

  • X-Auth-Token: required(string)

    Used to send a valid x-auth access token. Example: "X-Auth-Token: 'access_token'" where 'access_token' must be replaced by a valid access token.

Data access

API for listing and accessing binary data blobs uploaded by endpoints.

/applications/{appName}/binary-data get

get /applications/{appName}/binary-data

Returns a list of binary data blobs per endpoint.

Secured by OAuth 2.0 with scopes:
  • endpoint:read

BCX supports OAuth 2.0 for authenticating most API requests.

URI Parameters

  • appName: required(string)

    Application name.

    Example:

    bqa46oeg10l0thoh4m7g

Query Parameters

  • endpointId: optional (string)

    Zero or more endpoint ID(s). If not specified, data is returned for all available endpoints.

    Example:

    2ebaf0ab-76f3-4211-a27f-af310be8987f,8b4aec8a-0a13-4b92-ba0b-0a39cfd5e297
  • fromDate: required(datetime)

    ISO-8601 encoded start time from which to retrieve data blobs using their creation time.

    Example:

    2020-04-20T00:00:00.000Z
  • toDate: required(datetime)

    ISO-8601 encoded end time until which to retrieve data blobs using their creation time.

    Example:

    2020-04-22T00:00:00.000Z
  • sort: optional (one of ASC, DESC - default: ASC)

    Sorting order by timestamp.

HTTP status code 200

Array of objects, each containing arrays of binary data blob descriptors mapped by endpoint IDs.

Body

Media type: application/json

Type: array of objects

Example:

[
  {
    "2ebaf0ab-76f3-4211-a27f-af310be8987f": [
      {
        "id": "gdc35eeh31g0sfth8a3c",
        "name": "pic00243",
        "url": "s3://s3-server.example.com/example-tenant/example-application/2ebaf0ab-76f3-4211-a27f-af310be8987f/gdc35eeh31g0sfth8a3c",
        "size": 28534,
        "createdDate": "2017-04-20T11:19:57.848Z"
      },
      {
        "id": "etf58eeh31g0shth8a5f",
        "name": "pic00210",
        "url": "s3://s3-server.example.com/example-tenant/example-application/2ebaf0ab-76f3-4211-a27f-af310be8987f/etf58eeh31g0shth8a5f",
        "size": 82052,
        "createdDate": "2017-04-11T11:19:57.848Z"
      }
    ],
    "8b4aec8a-0a13-4b92-ba0b-0a39cfd5e297": [
      {
        "id": "ghr49eeh31g0sgth8a2w",
        "name": "pic61783",
        "url": "s3://s3-server.example.com/example-tenant/example-application/8b4aec8a-0a13-4b92-ba0b-0a39cfd5e297/ghr49eeh31g0sgth8a2w",
        "size": 68110,
        "createdDate": "2017-04-20T11:19:57.848Z"
      }
    ]
  }
]

HTTP status code 404

Requested application or endpoint is not found or the querying user is denied access.

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/{appName}/endpoints/{endpointId}/binary-data/data/last get

get /applications/{appName}/endpoints/{endpointId}/binary-data/data/last

Returns the most recent binary data blob payload.

Secured by OAuth 2.0 with scopes:
  • endpoint:read

BCX supports OAuth 2.0 for authenticating most API requests.

URI Parameters

  • appName: required(string)

    Application name.

    Example:

    bqa46oeg10l0thoh4m7g
  • endpointId: required(string)

    Identifier of the endpoint to operate on.

    Example:

    2ebaf0ab-76f3-4211-a27f-af310be8987f

HTTP status code 200

The most recent binary data blob payload returned in the response body.

Headers

  • Content-Type: required(string)

    Content-Type: application/octet-stream

  • Content-Disposition: required(string)

    Content-Disposition: attachment; filename=".bin"

Body

Media type: application/octet-stream

Type: byte array

HTTP status code 404

Requested application or endpoint or data blob is not found or the querying user is denied access.

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/{appName}/endpoints/{endpointId}/binary-data/{blobId} delete

delete /applications/{appName}/endpoints/{endpointId}/binary-data/{blobId}

Deletes a binary data blob by its ID.

Secured by OAuth 2.0 with scopes:
  • endpoint:update

BCX supports OAuth 2.0 for authenticating most API requests.

URI Parameters

  • appName: required(string)

    Application name.

    Example:

    bqa46oeg10l0thoh4m7g
  • endpointId: required(string)

    Identifier of the endpoint to operate on.

    Example:

    2ebaf0ab-76f3-4211-a27f-af310be8987f
  • blobId: required(string)

    Identifier of the binary data blob.

    Example:

    gdc35eeh31g0sath8a3c

HTTP status code 204

Binary data blob is successfully deleted.

HTTP status code 404

Requested application or endpoint or data blob is not found or the querying user is denied access.

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/{appName}/endpoints/{endpointId}/binary-data/{blobId}/data get

get /applications/{appName}/endpoints/{endpointId}/binary-data/{blobId}/data

Returns a binary data blob payload by its ID.

Secured by OAuth 2.0 with scopes:
  • endpoint:read

BCX supports OAuth 2.0 for authenticating most API requests.

URI Parameters

  • appName: required(string)

    Application name.

    Example:

    bqa46oeg10l0thoh4m7g
  • endpointId: required(string)

    Identifier of the endpoint to operate on.

    Example:

    2ebaf0ab-76f3-4211-a27f-af310be8987f
  • blobId: required(string)

    Identifier of the binary data blob.

    Example:

    gdc35eeh31g0sath8a3c

HTTP status code 200

Binary data blob payload returned in the response body.

Headers

  • Content-Type: required(string)

    Content-Type: application/octet-stream

  • Content-Disposition: required(string)

    Content-Disposition: attachment; filename=".bin"

Body

Media type: application/octet-stream

Type: byte array

HTTP status code 404

Requested application or endpoint or data blob is not found or the querying user is denied access.

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.