{
  "openapi": "3.0.3",
  "info": {
    "title": "Binary data Collection Extension service REST",
    "version": "v1",
    "description": ""
  },
  "servers": [
    {
      "url": "https://cloud.kaaiot.com/bcx/api/v1",
      "description": "API Server"
    }
  ],
  "paths": {
    "/binary-data": {
      "post": {
        "description": "Accepts a binary data blob from an endpoint.",
        "responses": {
          "201": {
            "description": "Binary data blob successfully uploaded.",
            "headers": {
              "Location": {
                "description": "URI in format `{schema}://{host}:{port}/applications/{appName}/endpoints/{endpointID}/binary-data/{blobId}`",
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "403": {
            "description": "Operation is not authorized: missing, expired, or invalid auth token."
          }
        },
        "security": [
          [
            "x_auth_token"
          ]
        ],
        "parameters": [
          {
            "name": "name",
            "in": "query",
            "description": "Arbitrary data blob name to be stored as an attribute.",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "pic00243.png"
          }
        ],
        "requestBody": {
          "content": {
            "application/octet-stream": {
              "schema": {
                "type": "object"
              }
            }
          }
        }
      }
    },
    "/files/{filename}": {
      "post": {
        "description": "Accepts a file from an endpoint.",
        "responses": {
          "204": {
            "description": "File successfully uploaded or overwritten."
          },
          "400": {
            "description": "Invalid request."
          },
          "403": {
            "description": "Operation is not authorized: missing, expired, or invalid auth token."
          }
        },
        "security": [
          [
            "x_auth_token"
          ]
        ],
        "requestBody": {
          "content": {
            "application/octet-stream": {
              "schema": {
                "type": "object"
              }
            }
          }
        }
      }
    },
    "/applications/{appName}/files": {
      "parameters": [
        {
          "name": "appName",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string"
          },
          "description": "Application name.",
          "example": "bqa46oeg10l0thoh4m7g"
        }
      ],
      "get": {
        "description": "Returns a list of files.",
        "responses": {
          "200": {
            "description": "Files are successfully retrieved.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FilesResponse"
                },
                "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
                }
              }
            }
          },
          "400": {
            "description": "Invalid request."
          },
          "403": {
            "description": "The querying user is denied access for requested endpoints."
          },
          "404": {
            "description": "Requested application is not found."
          }
        },
        "security": [
          {
            "oauth_2_0": [
              "endpoint:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "endpointId",
            "in": "query",
            "description": "Zero or more endpoint ID(s). If not specified, data is returned for all available endpoints.",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "2ebaf0ab-76f3-4211-a27f-af310be8987f,8b4aec8a-0a13-4b92-ba0b-0a39cfd5e297"
          },
          {
            "name": "name",
            "in": "query",
            "description": "filename. Supports partial match.",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "pic00243.png"
          },
          {
            "name": "fromDate",
            "in": "query",
            "description": "ISO-8601 encoded start time from which to retrieve data blobs using their creation time.",
            "required": false,
            "schema": {
              "type": "datetime"
            },
            "example": "2020-04-20T00:00:00+00:00"
          },
          {
            "name": "toDate",
            "in": "query",
            "description": "ISO-8601 encoded end time until which to retrieve data blobs using their creation time.",
            "required": false,
            "schema": {
              "type": "datetime"
            },
            "example": "2020-04-22T00:00:00+00:00"
          },
          {
            "name": "offset",
            "in": "query",
            "description": "The starting index from which the server should return data.",
            "required": false,
            "schema": {
              "type": "integer"
            },
            "example": 10
          },
          {
            "name": "limit",
            "in": "query",
            "description": "The maximum number of items to be returned.",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 20
            },
            "example": 2
          },
          {
            "name": "sort",
            "in": "query",
            "description": "Sorting order by timestamp.",
            "required": false,
            "schema": {
              "type": "string",
              "default": "ASC",
              "enum": [
                "ASC",
                "DESC"
              ]
            }
          }
        ]
      }
    },
    "/applications/{appName}/binary-data": {
      "parameters": [
        {
          "name": "appName",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string"
          },
          "description": "Application name.",
          "example": "bqa46oeg10l0thoh4m7g"
        }
      ],
      "get": {
        "description": "Returns a list of binary data blobs per endpoint.",
        "responses": {
          "200": {
            "description": "Array of objects, each containing arrays of binary data blob descriptors mapped by endpoint IDs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "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"
                      }
                    ]
                  }
                ]
              }
            }
          },
          "404": {
            "description": "Requested application or endpoint is not found or the querying user is denied access."
          }
        },
        "security": [
          {
            "oauth_2_0": [
              "endpoint:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "endpointId",
            "in": "query",
            "description": "Zero or more endpoint ID(s). If not specified, data is returned for all available endpoints.",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "2ebaf0ab-76f3-4211-a27f-af310be8987f,8b4aec8a-0a13-4b92-ba0b-0a39cfd5e297"
          },
          {
            "name": "fromDate",
            "in": "query",
            "description": "ISO-8601 encoded start time from which to retrieve data blobs using their creation time.",
            "required": true,
            "schema": {
              "type": "datetime"
            },
            "example": "2020-04-20T00:00:00+00:00"
          },
          {
            "name": "toDate",
            "in": "query",
            "description": "ISO-8601 encoded end time until which to retrieve data blobs using their creation time.",
            "required": true,
            "schema": {
              "type": "datetime"
            },
            "example": "2020-04-22T00:00:00+00:00"
          },
          {
            "name": "sort",
            "in": "query",
            "description": "Sorting order by timestamp.",
            "required": false,
            "schema": {
              "type": "string",
              "default": "ASC",
              "enum": [
                "ASC",
                "DESC"
              ]
            }
          }
        ]
      }
    },
    "/applications/{appName}/binary-data/list": {
      "parameters": [
        {
          "name": "appName",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string"
          },
          "description": "Application name.",
          "example": "bqa46oeg10l0thoh4m7g"
        }
      ],
      "get": {
        "description": "Returns a list of binary data blobs.",
        "responses": {
          "200": {
            "description": "Binary data blobs are successfully retrieved.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "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
                }
              }
            }
          },
          "404": {
            "description": "Requested application is not found."
          }
        },
        "security": [
          {
            "oauth_2_0": [
              "endpoint:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "endpointId",
            "in": "query",
            "description": "Zero or more endpoint ID(s). If not specified, data is returned for all available endpoints.",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "2ebaf0ab-76f3-4211-a27f-af310be8987f,8b4aec8a-0a13-4b92-ba0b-0a39cfd5e297"
          },
          {
            "name": "name",
            "in": "query",
            "description": "Blob name. Supports partial match.",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "pic00243.png"
          },
          {
            "name": "fromDate",
            "in": "query",
            "description": "ISO-8601 encoded start time from which to retrieve data blobs using their creation time.",
            "required": false,
            "schema": {
              "type": "datetime"
            },
            "example": "2020-04-20T00:00:00+00:00"
          },
          {
            "name": "toDate",
            "in": "query",
            "description": "ISO-8601 encoded end time until which to retrieve data blobs using their creation time.",
            "required": false,
            "schema": {
              "type": "datetime"
            },
            "example": "2020-04-22T00:00:00+00:00"
          },
          {
            "name": "offset",
            "in": "query",
            "description": "The starting index from which the server should return data.",
            "required": false,
            "schema": {
              "type": "integer"
            },
            "example": 10
          },
          {
            "name": "limit",
            "in": "query",
            "description": "The maximum number of items to be returned.",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 20
            },
            "example": 2
          },
          {
            "name": "sort",
            "in": "query",
            "description": "Sorting order by timestamp.",
            "required": false,
            "schema": {
              "type": "string",
              "default": "ASC",
              "enum": [
                "ASC",
                "DESC"
              ]
            }
          }
        ]
      }
    },
    "/applications/{appName}/endpoints/{endpointId}/files/{filename}": {
      "parameters": [
        {
          "name": "appName",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string"
          },
          "description": "Application name.",
          "example": "bqa46oeg10l0thoh4m7g"
        },
        {
          "name": "endpointId",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string"
          },
          "description": "Identifier of the endpoint to operate on.",
          "example": "2ebaf0ab-76f3-4211-a27f-af310be8987f"
        },
        {
          "name": "filename",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string"
          },
          "description": "Filename.",
          "example": "pic00243.png"
        }
      ],
      "get": {
        "description": "Returns a file.",
        "responses": {
          "200": {
            "description": "File returned in the response body.",
            "headers": {
              "Content-Type": {
                "description": "Content-Type: application/octet-stream\n",
                "schema": {
                  "type": "string"
                }
              },
              "Content-Disposition": {
                "description": "Content-Disposition: attachment; filename=\"filename\"\n",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/octet-stream": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "404": {
            "description": "Requested application or endpoint or file is not found or the querying user is denied access."
          }
        },
        "security": [
          {
            "oauth_2_0": [
              "endpoint:read"
            ]
          }
        ]
      },
      "delete": {
        "description": "Deletes a file.",
        "responses": {
          "204": {
            "description": "File is successfully deleted."
          },
          "404": {
            "description": "Requested application or endpoint or file is not found or the querying user is denied access."
          }
        },
        "security": [
          {
            "oauth_2_0": [
              "endpoint:update"
            ]
          }
        ]
      }
    },
    "/applications/{appName}/endpoints/{endpointId}/data/last": {
      "parameters": [
        {
          "name": "appName",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string"
          },
          "description": "Application name.",
          "example": "bqa46oeg10l0thoh4m7g"
        },
        {
          "name": "endpointId",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string"
          },
          "description": "Identifier of the endpoint to operate on.",
          "example": "2ebaf0ab-76f3-4211-a27f-af310be8987f"
        }
      ],
      "get": {
        "description": "Returns the most recent binary data blob payload.",
        "responses": {
          "200": {
            "description": "The most recent binary data blob payload returned in the response body.",
            "headers": {
              "Content-Type": {
                "description": "Content-Type: application/octet-stream\n",
                "schema": {
                  "type": "string"
                }
              },
              "Content-Disposition": {
                "description": "The Content-Disposition is attachment with 'blobId.bin' as the filename.\nIf attribute blob name is present, attachment with 'name' as the filename.\n",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/octet-stream": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "404": {
            "description": "Requested application or endpoint or data blob is not found or the querying user is denied access."
          }
        },
        "security": [
          {
            "oauth_2_0": [
              "endpoint:read"
            ]
          }
        ]
      }
    },
    "/applications/{appName}/endpoints/{endpointId}/{blobId}": {
      "parameters": [
        {
          "name": "appName",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string"
          },
          "description": "Application name.",
          "example": "bqa46oeg10l0thoh4m7g"
        },
        {
          "name": "endpointId",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string"
          },
          "description": "Identifier of the endpoint to operate on.",
          "example": "2ebaf0ab-76f3-4211-a27f-af310be8987f"
        },
        {
          "name": "blobId",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string"
          },
          "description": "Identifier of the binary data blob.",
          "example": "gdc35eeh31g0sath8a3c"
        }
      ],
      "delete": {
        "description": "Deletes a binary data blob by its ID.",
        "responses": {
          "204": {
            "description": "Binary data blob is successfully deleted."
          },
          "404": {
            "description": "Requested application or endpoint or data blob is not found or the querying user is denied access."
          }
        },
        "security": [
          {
            "oauth_2_0": [
              "endpoint:update"
            ]
          }
        ]
      }
    },
    "/applications/{appName}/endpoints/{endpointId}/{blobId}/data": {
      "parameters": [
        {
          "name": "appName",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string"
          },
          "description": "Application name.",
          "example": "bqa46oeg10l0thoh4m7g"
        },
        {
          "name": "endpointId",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string"
          },
          "description": "Identifier of the endpoint to operate on.",
          "example": "2ebaf0ab-76f3-4211-a27f-af310be8987f"
        },
        {
          "name": "blobId",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string"
          },
          "description": "Identifier of the binary data blob.",
          "example": "gdc35eeh31g0sath8a3c"
        }
      ],
      "get": {
        "description": "Returns a binary data blob payload by its ID.",
        "responses": {
          "200": {
            "description": "Binary data blob payload returned in the response body.",
            "headers": {
              "Content-Type": {
                "description": "Content-Type: application/octet-stream\n",
                "schema": {
                  "type": "string"
                }
              },
              "Content-Disposition": {
                "description": "The Content-Disposition is attachment with 'blobId.bin' as the filename.\nIf attribute blob name is present, attachment with 'name' as the filename.\n",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/octet-stream": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "404": {
            "description": "Requested application or endpoint or data blob is not found or the querying user is denied access."
          }
        },
        "security": [
          {
            "oauth_2_0": [
              "endpoint:read"
            ]
          }
        ]
      }
    }
  },
  "components": {
    "securitySchemes": {
      "oauth_2_0": {
        "type": "oauth2",
        "description": "BCX supports OAuth 2.0 for authenticating most API requests.\n",
        "flows": {
          "implicit": {
            "authorizationUrl": "https://auth.example.com/oauth/authorize",
            "scopes": {}
          }
        }
      },
      "x_auth_token": {
        "type": "oauth2",
        "description": "BCX requires X-Auth-Token for authenticating upload API requests.\nThe token must be retrieved in advance by endpoint from the `bcx` extension service using the regular communication channel.\n"
      }
    },
    "schemas": {
      "FileResponse": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "Filename."
          },
          "endpointId": {
            "type": "string",
            "description": "Identifier of the endpoint to operate on."
          },
          "url": {
            "type": "string",
            "description": "Location of the file."
          },
          "size": {
            "type": "integer",
            "description": "Total sum of bytes."
          },
          "createdDate": {
            "type": "string",
            "format": "rfc3339",
            "description": "File creation date in ISO 8601 format."
          },
          "updatedDate": {
            "type": "string",
            "format": "rfc3339",
            "description": "File last update date in ISO 8601 format."
          }
        },
        "required": [
          "name",
          "endpointId",
          "createdDate",
          "updatedDate"
        ]
      },
      "FilesResponse": {
        "type": "object",
        "properties": {
          "content": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/FileResponse"
            }
          },
          "totalElements": {
            "type": "integer",
            "description": "Total number of files."
          }
        },
        "required": [
          "totalElements"
        ]
      }
    }
  }
}