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'