swagger: '2.0'
info:
  title: Data Exchange API
  version: '3.0.2'
  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.
    <br>
    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 <br />
      <li/> private, or
      <li/> public (within a tenant only)
    <br />
    When looking to p[lace 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. <br />
    Allowed and safe characters to use in both filename and directyory names
    are the following:
      <li/> Alphanumeric characters [0-9a-zA-Z]
      <li/> Special characters -, _, ., (, ),  and the space character
    The following are examples of valid object key names:
      <li/> 4my-data
      <li/> _test_dir./myfile.csv

    <b>Not allowed</b> is using &$@=;:+,?,\^{}%`[]"<>#|~!*' in
    filenames and directory names.<br />

    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-1000001700/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.<br />
        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.<br/>
      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:<br>
            {
              name: 'name',
              type: 'CSV',
              parentId: 'parentId'
            }.<br />
            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. <br />
      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.<br />
        Changing the parentId to a parent that already contains a folder
        with the same name is not possible, an error will be thrown.<br />
      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'
