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

post
post

Accepts a binary data blob from an endpoint.

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.

    Example:

    pic00243.png

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.

File upload

API for uploading file from connected endpoints.

post
post

Accepts a file from an endpoint.

Accepts a file 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.

URI Parameters

  • filename: required(string)

    Filename.

    Example:

    pic00243.png

Body

Media type: application/octet-stream

Type: byte array

HTTP status code 204

File successfully uploaded or overwritten.

HTTP status code 400

Invalid request.

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.

get
get

Returns a list of files.

Returns a list of files.

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

    filename. Supports partial match.

    Example:

    pic00243.png
  • fromDate: (datetime)

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

    Example:

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

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

    Example:

    2020-04-22T00:00:00.000Z
  • offset: (integer)

    The starting index from which the server should return data.

    Example:

    10
  • limit: (integer - default: 20)

    The maximum number of items to be returned.

    Example:

    2
  • sort: (one of ASC, DESC - default: ASC)

    Sorting order by timestamp.

HTTP status code 200

Files are successfully retrieved.

Body

Media type: application/json

Type: object

Properties
  • content: required(array of file-api-types.FileResponse)

    Items: FileResponse

    • name: required(string)

      Filename.

    • endpointId: required(string)

      Identifier of the endpoint to operate on.

    • url: (string)

      Location of the file.

    • size: (integer)

      Total sum of bytes.

    • createdDate: required(datetime)

      File creation date in ISO 8601 format.

    • updatedDate: required(datetime)

      File last update date in ISO 8601 format.

  • totalElements: required(integer)

    Total number of files.

Example:

{
  "content": [
    {
      "endpointId": "2ebaf0ab-76f3-4211-a27f-af310be8987f",
      "name": "pic00243.png",
      "url": "s3://s3-server.example.com/example-tenant/example-application/2ebaf0ab-76f3-4211-a27f-af310be8987f/log00243",
      "size": 28534,
      "createdDate": "2017-04-20T11:19:57.848Z",
      "updatedDate": "2017-04-20T11:19:57.848Z"
    },
    {
      "endpointId": "2ebaf0ab-76f3-4211-a27f-af310be8987f",
      "name": "pic00243.png",
      "url": "s3://s3-server.example.com/example-tenant/example-application/2ebaf0ab-76f3-4211-a27f-af310be8987f/log00210",
      "size": 82052,
      "createdDate": "2017-04-11T11:19:57.848Z",
      "updatedDate": "2017-04-11T11:19:57.848Z"
    }
  ],
  "totalElements": 2
}

HTTP status code 400

Invalid request.

HTTP status code 403

The querying user is denied access for requested endpoints.

HTTP status code 404

Requested application is 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.

get
get

Returns a list of binary data blobs per endpoint.

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.png",
        "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.png",
        "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.png",
        "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.

get
get

Returns a list of binary data blobs.

Returns a list of binary data blobs.

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

    Blob name. Supports partial match.

    Example:

    pic00243.png
  • fromDate: (datetime)

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

    Example:

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

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

    Example:

    2020-04-22T00:00:00.000Z
  • offset: (integer)

    The starting index from which the server should return data.

    Example:

    10
  • limit: (integer - default: 20)

    The maximum number of items to be returned.

    Example:

    2
  • sort: (one of ASC, DESC - default: ASC)

    Sorting order by timestamp.

HTTP status code 200

Binary data blobs are successfully retrieved.

Body

Media type: application/json

Type: array of objects

Example:

{
  "content": [
    {
      "id": "gdc35eeh31g0sfth8a3c",
      "endpointId": "2ebaf0ab-76f3-4211-a27f-af310be8987f",
      "name": "pic00243.png",
      "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",
      "endpointId": "2ebaf0ab-76f3-4211-a27f-af310be8987f",
      "name": "pic00210.png",
      "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"
    },
    {
      "id": "ghr49eeh31g0sgth8a2w",
      "endpointId": "8b4aec8a-0a13-4b92-ba0b-0a39cfd5e297",
      "name": "pic61783.png",
      "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"
    }
  ],
  "totalElements": 3
}

HTTP status code 404

Requested application is 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.

get delete
get

Returns a file.

delete

Deletes a file.

Returns a file.

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
  • filename: required(string)

    Filename.

    Example:

    pic00243.png

HTTP status code 200

File returned in the response body.

Headers

  • Content-Type: required(string)

    Content-Type: application/octet-stream

  • Content-Disposition: required(string)

    Content-Disposition: attachment; filename="filename"

Body

Media type: application/octet-stream

Type: byte array

HTTP status code 404

Requested application or endpoint or file 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.

Deletes a file.

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
  • filename: required(string)

    Filename.

    Example:

    pic00243.png

HTTP status code 204

File is successfully deleted.

HTTP status code 404

Requested application or endpoint or file 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.

get
get

Returns the most recent binary data blob payload.

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)

    The Content-Disposition is attachment with 'blobId.bin' as the filename. If attribute blob name is present, attachment with 'name' as the filename.

    Example:

    attachment; filename="pic00243.png"

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.

delete
delete

Deletes a binary data blob by its ID.

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

Returns a binary data blob payload by its ID.

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)

    The Content-Disposition is attachment with 'blobId.bin' as the filename. If attribute blob name is present, attachment with 'name' as the filename.

    Example:

    attachment; filename="pic00243.png"

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.