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: (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: (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: (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: (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.

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: (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.