swagger: '2.0' info: title: Data Exchange API version: '3.0.1' x-released: 'no' x-visibility: external description: >- Offers data transfer operations as part of the Analytics package, in a single endpoint providing various operations like upload/download, move, (recursive) delete, share within tenant.
It also provides an abstraction that helps callers easily share files and folders between the users of tHe same tenant, while allowing uploads with different visibilities
  • private, or
  • public (within a tenant only)
    When looking to place a file or directory (either when creating a new one or moving it) into the root of the storage, simply set the parentId of the file or folder to one of the "_PUBLIC_ROOT_ID" or "_PRIVATE_ROOT_ID" allowing in this way to specify its visibility space.
    Allowed and safe characters to use in both filename and directyory names are the following:
  • Alphanumeric characters [0-9a-zA-Z]
  • Special characters -, _, ., (, ), and the space character The following are examples of valid object key names:
  • 4my-data
  • _test_dir./myfile.csv Not allowed is using &$@=;:+,?,\^{}%`[]"<>#|~!*' in filenames and directory names.
    The maximum length of the composed path, that is filename and directories names separated by '/' that is used in a request is 1024 bytes in UTF-8 encoding. definitions: Directory: type: object properties: id: type: string format: uuid name: type: string parentId: type: string format: string modifiedDate: type: string format: date-time modifiedBy: type: string format: string example: id: '30c01d19-72c9-4b3e-b4e4-6d076196a305' name: 'myFolder' parentId: 'dfb40306-b928-4e25-8b71-a200f8fef514' modifiedDate: '2018-02-29 22:35:21.992 -09' modifiedBy: 'donald@knuth.com' File: type: object properties: id: type: string format: uuid parentId: type: string format: string name: type: string type: type: string sizeInBytes: type: integer format: int64 modifiedDate: type: string format: date-time modifiedBy: type: string format: string example: id: '434f6cf2-6d8f-491a-bf6b-c4cedd696741' name: 'myFile' type: 'CSV' parentId: 'afb4h40u-b4p8-4425-8b74-a2b3f4beh514' sizeInBytes: 992811022 modifiedDate: '2018-02-29 22:35:21.992 -05' modifiedBy: 'alan@turing.co.uk' ResourcePatch: type: object properties: name: type: string type: type: string parentId: type: string format: string example: name: 'New name' type: 'Parquet' parentId: 'afb4h40u-b4p8-4425-8b74-a2b3f4beh514' Files: type: array items: $ref: '#/definitions/File' Directories: type: array items: $ref: '#/definitions/Directory' Page: type: object properties: number: type: integer description: Number of current page. size: type: integer description: Size of the page totalPages: type: integer description: Number of the total pages totalElements: type: integer description: Total of the elements DirectoriesFilesArray: type: object properties: files: type: array items: $ref: '#/definitions/Files' directories: type: array items: $ref: '#/definitions/Directories' page: $ref: '#/definitions/Page' VndError: type: object properties: code: type: string example: mdsp.analytics.dataexchange.error readOnly: true logref: type: string example: c06534d4-6f0e-11e8-adc0-fa7ae01bbebc readOnly: true message: type: string example: Error message readOnly: true VndErrors: type: object properties: errors: type: array items: $ref: '#/definitions/VndError' responses: 200-file-download: description: File downloaded successfully. 200-file-update: description: File was updated successfully. schema: $ref: '#/definitions/File' 200-file-properties: description: File information was retrieved successfully. schema: $ref: '#/definitions/File' 200-directories-list: description: Directory content listed successfully. schema: $ref: '#/definitions/DirectoriesFilesArray' 200-directory-properties: description: Directory information was retrieved successfully. schema: $ref: '#/definitions/Directory' 200-directory-update: description: Directory was updated successfully. schema: $ref: '#/definitions/Directory' 201-file-upload: description: File was uploaded successfully. schema: $ref: '#/definitions/File' 201-directory-create: description: Directory was created successfully. schema: $ref: '#/definitions/Directory' 204-file-deletion: description: File was deleted successfully. 204-directory-deletion: description: Directory was deleted successfully. 400-bad-request-parameter: description: Provided parameter is missing or malformed (e.g. wrong parent IDs). schema: $ref: '#/definitions/VndErrors' 403-forbidden-resource: description: Forbbiden - The user or tenant does not have access to the specified resource or specified parent. schema: $ref: '#/definitions/VndErrors' 404-not-found: description: The requested resource could not be found. schema: $ref: '#/definitions/VndErrors' 500-internal: description: The service encountered an unexpected error. schema: $ref: '#/definitions/VndErrors' 503-unavailable: description: The service is currently unavailable. schema: $ref: '#/definitions/VndErrors' schemes: - https basePath: /api/dataexchange/v3 tags: - name: File Operations description: Operations on single file and their metadata. - name: Directory Operations description: Directory operations. Same paradigm as known from file systems. Directory can have a series of sub-directories and files as their content. Operations is done on the metadata only (i.e. name). securityDefinitions: dataexchange: type: oauth2 flow: accessCode authorizationUrl: 'https://oauth.simple.api/authorization' tokenUrl: 'https://oauth.simple.api/token' scopes: pl.de.r: allows downloading and getting information about stored objects pl.de.w: allows uploading, deleting and copying objects; also implies pl.de.r paths: '/files': post: tags: - File Operations summary: Performs a new file upload security: - dataexchange: - pl.de.w description: >- Uploads a file using the specified form data parameters, and returns the created file resource.
    The service verifies whether the user or the tenant under which the operation occurs has access to the specified parent and generates an error in case of an unautorhized access.
    operationId: uploadNewfile consumes: - multipart/form-data - application/octet-stream - application/json produces: - application/json parameters: - in: formData name: metadata type: string format: json required: true description: >- JSON file containing required file properties, as the name and parent. The expected JSON format is as follows:
    { "name": "name", "type": "CSV", "parentId": "parentId" }.
    The values for "parentId" can be either "_PUBLIC_ROOT_ID", "_PRIVATE_ROOT_ID" or a valid directory Id. - in: formData name: file type: file required: true description: | the file stream that holds the file content responses: '201': $ref: '#/responses/201-file-upload' '400': $ref: '#/responses/400-bad-request-parameter' '403': $ref: '#/responses/403-forbidden-resource' '500': $ref: '#/responses/500-internal' '503': $ref: '#/responses/503-unavailable' '/files/{id}': get: #download tags: - File Operations summary: >- Performs a file download description: >- Downloads the file identified by the specified ID. security: - dataexchange: - pl.de.r - pl.de.w operationId: download produces: - multipart/form-data parameters: - name: id in: path description: The ID of the file which is to be downloaded. required: true type: string responses: '200': $ref: '#/responses/200-file-download' '400': $ref: '#/responses/400-bad-request-parameter' '403': $ref: '#/responses/403-forbidden-resource' '404': $ref: '#/responses/404-not-found' '500': $ref: '#/responses/500-internal' '503': $ref: '#/responses/503-unavailable' put: #update (upload with overwrite default true) tags: - File Operations summary: >- Allows users to update a file's contents. If the file does not already exists already, or permissions are not sufficient, an error is returned. security: - dataexchange: - pl.de.w description: Uploads a file on top of an existing file operationId: updateFile consumes: - multipart/form-data - application/octet-stream - application/json produces: - application/json parameters: - in: formData name: file type: file required: true description: | The stream providing the file content. - in: path name: id type: string format: UUID required: true description: >- the file that needs to be updated responses: '200': $ref: '#/responses/200-file-update' '400': $ref: '#/responses/400-bad-request-parameter' '403': $ref: '#/responses/403-forbidden-resource' '404': $ref: '#/responses/404-not-found' '500': $ref: '#/responses/500-internal' '503': $ref: '#/responses/503-unavailable' delete: tags: - File Operations summary: Performs a file deletion along with its associated metadata. security: - dataexchange: - pl.de.w description: Deletes a file (both metadata and the actual content). produces: - application/json consumes: - application/json parameters: - name: id in: path description: the fileId that was obtained when the file was uploaded required: true type: string operationId: deleteFile responses: '204': $ref: '#/responses/204-file-deletion' '400': $ref: '#/responses/400-bad-request-parameter' '403': $ref: '#/responses/403-forbidden-resource' '404': $ref: '#/responses/404-not-found' '500': $ref: '#/responses/500-internal' '503': $ref: '#/responses/503-unavailable' '/files/{id}/properties': get: tags: - File Operations summary: >- Retrieves the file properties (metadata). security: - dataexchange: - pl.de.w description: Retrieves metadata of the file identified by the specified ID. operationId: getFileProperties produces: - application/json consumes: - application/json parameters: - name: id in: path type: string format: UUID required: true description: The ID of the file for which the metadata is to be retrieved. responses: '200': $ref: '#/responses/200-file-properties' '400': $ref: '#/responses/400-bad-request-parameter' '403': $ref: '#/responses/403-forbidden-resource' '404': $ref: '#/responses/400-bad-request-parameter' '500': $ref: '#/responses/500-internal' '503': $ref: '#/responses/503-unavailable' patch: tags: - File Operations summary: Allows updating the properties (metadata) of an existing file. security: - dataexchange: - pl.de.w description: >- Allows updating specific properties associated with the file, namely its name and parent (by ID). Updating the visibility (namely tenant-wide or user-only) for a file is not available but can be achieved via changing the current file's parent to a directory that has a different visibility space.
    produces: - application/json consumes: - application/json parameters: - name: id in: path type: string format: UUID required: true description: The ID of the file which will have its properties updated. - name: options in: body required: true schema: $ref: '#/definitions/ResourcePatch' responses: '200': $ref: '#/responses/200-file-properties' '400': $ref: '#/responses/400-bad-request-parameter' '403': $ref: '#/responses/403-forbidden-resource' '404': $ref: '#/responses/400-bad-request-parameter' '500': $ref: '#/responses/500-internal' '503': $ref: '#/responses/503-unavailable' '/directories': post: tags: - Directory Operations summary: Creates a directory security: - dataexchange: - pl.de.w description: Creates a directory with specified parent or in root operationId: createDirectory consumes: - application/json produces: - application/json parameters: - name: metadata in: body required: true schema: $ref: '#/definitions/ResourcePatch' description: >- Parent directoryId under which this directory will be created. responses: '201': $ref: '#/responses/201-directory-create' '400': $ref: '#/responses/400-bad-request-parameter' '403': $ref: '#/responses/403-forbidden-resource' '404': $ref: '#/responses/400-bad-request-parameter' '500': $ref: '#/responses/500-internal' '503': $ref: '#/responses/503-unavailable' '/directories/{id}/properties': get: tags: - Directory Operations summary: >- Retreives updatable directory options, i.e the name and the parentId. security: - dataexchange: - pl.de.w description: Retrieves directory properties operationId: getDirectoryProperties produces: - application/json consumes: - application/json parameters: - name: id in: path type: string format: UUID required: true description: the ID of the directory responses: '200': $ref: '#/responses/200-directory-update' '400': $ref: '#/responses/400-bad-request-parameter' '403': $ref: '#/responses/403-forbidden-resource' '404': $ref: '#/responses/400-bad-request-parameter' '500': $ref: '#/responses/500-internal' '503': $ref: '#/responses/503-unavailable' patch: tags: - Directory Operations summary: >- Allows updating directory's properties. security: - dataexchange: - pl.de.w description: >- Allows updating directory metadata, including the parentId (which triggers a move of the current directory), or its visibility by moving it under a parentId that has a different visibility, causing this change to propagate to its inner contents.
    Changing the parentId to a parent that already contains a folder with the same name is not possible, an error will be thrown.
    produces: - application/json consumes: - application/json parameters: - name: id in: path type: string format: UUID required: true description: the id of the file to be published - name: options in: body required: true description: the 'type' key is ignored if provided schema: $ref: '#/definitions/ResourcePatch' responses: '200': $ref: '#/responses/200-directory-properties' '400': $ref: '#/responses/400-bad-request-parameter' '403': $ref: '#/responses/403-forbidden-resource' '404': $ref: '#/responses/400-bad-request-parameter' '500': $ref: '#/responses/500-internal' '503': $ref: '#/responses/503-unavailable' '/directories/{id}': get: tags: - Directory Operations summary: >- Performs a listing of all the accessible files and folders from current specified directory; recursive parameter can also be specified for this operation description: >- Using GET on this endpoint to get a list of the source's contents security: - dataexchange: - pl.de.r - pl.de.w operationId: listDirectoryContents produces: - application/json parameters: - name: id in: path description: >- Specifies the id for which it will list the contents. By convention, when listing a root folder also implies specifying the visibility that the caller is looking after, that is, if listing the private space root, then this parameter requires "_PUBLIC_ROOT_ID" or "_PRIVATE_ROOT_ID" value instead of a real directory id. required: true type: string - name: pageNumber in: query type: integer format: int32 minimum: 0 maximum: 10000 - name: pageSize in: query type: integer format: int32 minimum: 0 maximum: 500 - name: filter in: query required: false type: string minLength: 3 description: >- Filters the output based on the wildcard string with * as the wildcard, it requires at least 3 non * characters in order to provide a result. This filter applies to both directories and files responses: '200': $ref: '#/responses/200-directories-list' '400': $ref: '#/responses/400-bad-request-parameter' '403': $ref: '#/responses/403-forbidden-resource' '404': $ref: '#/responses/400-bad-request-parameter' '500': $ref: '#/responses/500-internal' '503': $ref: '#/responses/503-unavailable' delete: tags: - Directory Operations summary: Performs a directory deletion security: - dataexchange: - pl.de.w description: Deletes a directory and its contents if recursive=true produces: - application/json consumes: - application/json operationId: deleteDirectory parameters: - name: id in: path description: the directory id that was obtained when the directory was created required: true type: string - name: recursive in: query type: boolean default: false description: specifies if the deletion will be performed recursively responses: '204': $ref: '#/responses/204-directory-deletion' '400': $ref: '#/responses/400-bad-request-parameter' '403': $ref: '#/responses/403-forbidden-resource' '404': $ref: '#/responses/400-bad-request-parameter' '500': $ref: '#/responses/500-internal' '503': $ref: '#/responses/503-unavailable'