

# API spec in YAML
swagger: '2.0'
info:
  title: Bucket Service for "Metadata" resources
  description: Manages buckets of files representing a Metadata resource
  version: "1.0.0"
# the domain of the service
host: haleconnect.com
# array of all schemes that your API supports
schemes:
  - https
basePath: /store/metadata
produces:
  - application/json
security:
  - bearer: []

paths:
  /buckets:
    post:
      summary: Create a new bucket in the current context
      tags:
        - Buckets
      consumes:
        - application/json
      parameters:
        - $ref: '#/parameters/context'
        - in: body
          name: body
          description: Information on the bucket to be created
          required: true
          schema:
            $ref: '#/definitions/NewBucket'
      responses:
        200:
          description: Bucket created
          schema:
            $ref: '#/definitions/BucketIdent'
        default:
          description: Error creating bucket
          schema:
            $ref: '#/definitions/Feedback'
    get:
      summary: List all buckets
      tags:
        - Buckets
      parameters:
        - $ref: '#/parameters/context'
        - $ref: '#/parameters/toDetails'
      responses:
        200:
          description: OK
          schema:
            type: array
            items:
              $ref: '#/definitions/BucketInfo'
        default:
          description: Error retrieving buckets
          schema:
            $ref: '#/definitions/Feedback'

  /buckets/context:
    parameters:
      - $ref: '#/parameters/context'
    get:
      summary: List buckets in the current context
      tags:
        - Buckets
      parameters:
        - $ref: '#/parameters/toDetails'
      responses:
        200:
          description: OK
          schema:
            type: array
            items:
              $ref: '#/definitions/BucketInfo'
        default:
          description: Error retrieving buckets
          schema:
            $ref: '#/definitions/Feedback'

  /buckets/by/{property}/{value}:
    parameters:
      - in: path
        name: property
        required: true
        type: string
        description: Property name
      - in: path
        name: value
        required: true
        type: string
        description: Property value
    get:
      summary: List all buckets with a specific property value
      tags:
        - Buckets
      responses:
        200:
          description: OK
          schema:
            type: array
            items:
              $ref: '#/definitions/BucketInfo'
        default:
          description: Error retrieving buckets
          schema:
            $ref: '#/definitions/Feedback'

  /buckets/{ownerType}/{ownerId}:
    parameters:
      - $ref: '#/parameters/ownerType'
      - $ref: '#/parameters/ownerId'
    post:
      summary: Create a new bucket for a specific owner
      tags:
        - Buckets
      consumes:
        - application/json
      parameters:
        - in: body
          name: body
          description: Information on the bucket to be created
          required: true
          schema:
            $ref: '#/definitions/NewBucket'
      responses:
        200:
          description: Bucket created
          schema:
            $ref: '#/definitions/BucketIdent'
        default:
          description: Error creating bucket
          schema:
            $ref: '#/definitions/Feedback'
    get:
      summary: List available buckets for an owner
      parameters:
        - $ref: '#/parameters/toDetails'
        - $ref: '#/parameters/filter'
        - $ref: '#/parameters/sort'
      tags:
        - Buckets
      responses:
        200:
          description: OK
          schema:
            type: array
            items:
              $ref: '#/definitions/BucketInfo'
        default:
          description: Error retrieving buckets
          schema:
            $ref: '#/definitions/Feedback'

    delete:
      summary: Delete all the buckets belonging to an organisation
      tags:
        - Buckets
      responses:
        200:
          description: OK
          schema:
            $ref: '#/definitions/Feedback'
        default:
          description: Deleting the buckets failed
          schema:
            $ref: '#/definitions/Feedback'

  /buckets/{ownerType}/{ownerId}/{bucket}/clone:
    parameters:
      - $ref: '#/parameters/ownerType'
      - $ref: '#/parameters/ownerId'
      - $ref: '#/parameters/bucketId'
    post:
      summary: Clones a bucket
      tags:
        - Buckets
      responses:
        200:
          description: Bucket cloned
          schema:
            $ref: '#/definitions/BucketIdent'
        default:
          description: Error cloning bucket information
          schema:
            $ref: '#/definitions/Feedback'


  /buckets/{ownerType}/{ownerId}/{bucket}:
    parameters:
      - $ref: '#/parameters/ownerType'
      - $ref: '#/parameters/ownerId'
      - $ref: '#/parameters/bucketId'
    get:
      summary: Get information on a bucket
      tags:
        - Buckets
      responses:
        200:
          description: OK
          schema:
            $ref: '#/definitions/BucketDetail'
        default:
          description: Error retrieving bucket information
          schema:
            $ref: '#/definitions/Feedback'
    delete:
      summary: Delete the bucket
      tags:
        - Buckets
      responses:
        200:
          description: OK
          schema:
            $ref: '#/definitions/Feedback'
        default:
          description: Deleting the bucket failed
          schema:
            $ref: '#/definitions/Feedback'

  /buckets/{ownerType}/{ownerId}/{bucket}/p/{name}:
    parameters:
      - $ref: '#/parameters/ownerType'
      - $ref: '#/parameters/ownerId'
      - $ref: '#/parameters/bucketId'
      - $ref: '#/parameters/propertyName'
    put:
      summary: Set a bucket property
      tags:
        - Buckets
      consumes:
        - text/plain; charset=utf-8
        - application/json
      parameters:
        - $ref: '#/parameters/propertyValue'
      responses:
        200:
          description: On successful update.
          schema:
            $ref: '#/definitions/Feedback'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Feedback'
    delete:
      summary: Delete a bucket property
      tags:
        - Buckets
      responses:
        200:
          description: On successful update.
          schema:
            $ref: '#/definitions/Feedback'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Feedback'

  /buckets/{ownerType}/{ownerId}/{bucket}/name:
    parameters:
      - $ref: '#/parameters/ownerType'
      - $ref: '#/parameters/ownerId'
      - $ref: '#/parameters/bucketId'
    put:
      summary: Set the bucket name
      tags:
        - Buckets
      consumes:
        - text/plain; charset=utf-8
      parameters:
        - $ref: '#/parameters/propertyValue'
      responses:
        200:
          description: On successful update.
          schema:
            $ref: '#/definitions/Feedback'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Feedback'

  /buckets/{ownerType}/{ownerId}/{bucket}/p:
    parameters:
      - $ref: '#/parameters/ownerType'
      - $ref: '#/parameters/ownerId'
      - $ref: '#/parameters/bucketId'
    put:
      summary: Set custom bucket properties
      tags:
        - Buckets
      consumes:
        - application/json
      parameters:
        - in: body
          name: body
          description: Custom bucket properties as arbitrary Json object
          required: true
          schema:
            type: object
      responses:
        200:
          description: On successful update.
          schema:
            $ref: '#/definitions/Feedback'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Feedback'

  /buckets/{ownerType}/{ownerId}/{bucket}/files:
    parameters:
      - $ref: '#/parameters/ownerType'
      - $ref: '#/parameters/ownerId'
      - $ref: '#/parameters/bucketId'
    get:
      summary: Get information on files on a bucket path
      tags:
        - Files
      responses:
        200:
          description: OK
          schema:
            $ref: '#/definitions/PathInfo'
        404:
          description: The path does not exist
          schema:
            $ref: '#/definitions/Feedback'
        default:
          description: Error retrieving path information
          schema:
            $ref: '#/definitions/Feedback'

  /buckets/{ownerType}/{ownerId}/{bucket}/metadata:
    parameters:
      - $ref: '#/parameters/ownerType'
      - $ref: '#/parameters/ownerId'
      - $ref: '#/parameters/bucketId'
    get:
      summary: Get bucket files metadata
      tags:
        - Files
      responses:
        200:
          description: OK
          schema:
            type: array
            items:
              $ref: '#/definitions/FileMetadata'
        404:
          description: The path does not exist
          schema:
            $ref: '#/definitions/Feedback'
        default:
          description: Error retrieving path information
          schema:
            $ref: '#/definitions/Feedback'

  /buckets/{ownerType}/{ownerId}/{bucket}/cleanMetadata:
    parameters:
      - $ref: '#/parameters/ownerType'
      - $ref: '#/parameters/ownerId'
      - $ref: '#/parameters/bucketId'
    post:
      summary: Clean the file metadata for the given dataset
      tags:
        - Files
      consumes:
        - "" # override default (application/json) where endpoint will complain on no body
      responses:
        200:
          description: OK
          schema:
            type: array
            items:
              $ref: '#/definitions/CleanMetadataResult'
        default:
          description: Error cleaning file metadata
          schema:
            $ref: '#/definitions/Feedback'
            
  # duplicate of above with path parameter added
  /buckets/{ownerType}/{ownerId}/{bucket}/files/{path}:
    parameters:
      - $ref: '#/parameters/ownerType'
      - $ref: '#/parameters/ownerId'
      - $ref: '#/parameters/bucketId'
      - $ref: '#/parameters/bucketPath'
    get:
      summary: Get information on files on a bucket path
      tags:
        - Files
      responses:
        200:
          description: OK
          schema:
            $ref: '#/definitions/PathInfo'
        404:
          description: The path does not exist
          schema:
            $ref: '#/definitions/Feedback'
        default:
          description: Error retrieving path information
          schema:
            $ref: '#/definitions/Feedback'

  /buckets/{ownerType}/{ownerId}/{bucket}/raw:
    parameters:
      - $ref: '#/parameters/ownerType'
      - $ref: '#/parameters/ownerId'
      - $ref: '#/parameters/bucketId'
    post:
      summary: Add files to the bucket
      tags:
        - Files
      consumes:
        - multipart/form-data
      parameters:
        - in: formData
          name: file
          required: true
          type: file
          # allowMultiple: true
        # - in: formData
        #   name: fileName
        #   required: false
        #   type: string
        # - in: formData
        #   name: extract
        #   required: false
        #   type: string
      responses:
        200:
          description: OK
          schema:
            $ref: '#/definitions/Feedback'
        default:
          description: Failed to upload file
          schema:
            $ref: '#/definitions/Feedback'

  /buckets/{ownerType}/{ownerId}/{bucket}/url:
    parameters:
      - $ref: '#/parameters/ownerType'
      - $ref: '#/parameters/ownerId'
      - $ref: '#/parameters/bucketId'
    post:
      summary: Add files to the bucket from url
      tags:
        - Files
      consumes:
        - application/json
      parameters:
        - in: body
          name: body
          description: URLs and WFS endpoints to download from.
          required: true
          schema:
            type: object
            properties:
              urls:
                description: Address of files to be downloaded
                type: array
                items:
                  type: object
                  properties:
                    url:
                      description: file url
                      type: string
                    path:
                      description: optional. upload path in bucket
                      type: string
              wfs:
                description: Address of files to be downloaded
                type: array
                items:
                  type: object
                  properties:
                    url:
                      description: wfs url
                      type: string
                    featureType: 
                      description: wfs feature type
                      type: string
                    nameSpaces: 
                      description: wfs name spaces
                      type: string
                    featureID: 
                      description: wsf feature id
                      type: string
                    sortBy: 
                      description: wfs sort by
                      type: string
                    propertyName: 
                      description: wfs property name
                      type: string
                    count: 
                      description: wfs count
                      type: string
                    username: 
                      description: wfs login username
                      type: string
                    password: 
                      description: wfs login password
                      type: string

      responses:
        200:
          description: OK
          schema:
            $ref: '#/definitions/Feedback'
        default:
          description: Failed to upload file
          schema:
            $ref: '#/definitions/Feedback'

  /buckets/{ownerType}/{ownerId}/{bucket}/reload:
    parameters:
      - $ref: '#/parameters/ownerType'
      - $ref: '#/parameters/ownerId'
      - $ref: '#/parameters/bucketId'
    post:
      summary: Redownloads file from original URL
      tags:
        - Files
      consumes:
        - application/json
      parameters:
        - in: body
          name: body
          description: File names to be redownloaded from URLs
          required: true
          schema:
            type: object
            properties:
              fileNames:
                description: Name of file to be redownloaded
                type: array
                items:
                  type: string
      responses:
        200:
          description: OK
          schema:
            $ref: '#/definitions/Feedback'
        default:
          description: Failed to upload file
          schema:
            $ref: '#/definitions/Feedback'

  /buckets/{ownerType}/{ownerId}/{bucket}/raw/{path}:
    parameters:
      - $ref: '#/parameters/ownerType'
      - $ref: '#/parameters/ownerId'
      - $ref: '#/parameters/bucketId'
      - $ref: '#/parameters/bucketPath'
    put:
      summary: Add or replace a file
      tags:
        - Files
      consumes:
        - multipart/form-data
      parameters:
        - in: formData
          name: file
          required: true
          type: file
      responses:
        200:
          description: OK
          schema:
            $ref: '#/definitions/Feedback'
        default:
          description: Error uploading the file
          schema:
            $ref: '#/definitions/Feedback'
    delete:
      summary: Delete a file
      tags:
        - Files
      responses:
        200:
          description: OK
          schema:
            $ref: '#/definitions/Feedback'
        404:
          description: The file was not found
          schema:
            $ref: '#/definitions/Feedback'
        default:
          description: Deleting the file failed
          schema:
            $ref: '#/definitions/Feedback'
    get:
      summary: Access a raw file
      tags:
        - Files
      responses:
        200:
          description: OK
        404:
          description: The file was not found
          schema:
            $ref: '#/definitions/Feedback'
        default:
          description: Error accessing the file
          schema:
            $ref: '#/definitions/Feedback'

  /buckets/{ownerType}/{ownerId}/{bucket}/zip:
    parameters:
      - $ref: '#/parameters/ownerType'
      - $ref: '#/parameters/ownerId'
      - $ref: '#/parameters/bucketId'
    get:
      summary: Get a zip file containing all of the project files
      tags:
        - Files
      responses:
        200:
          description: OK
          schema:
            $ref: '#/definitions/Feedback'
        404:
          description: The bucket or one of its files was not found
          schema:
            $ref: '#/definitions/Feedback'

        default:
          description: Error retrieving bucket information
          schema:
            $ref: '#/definitions/Feedback'


  /s3auth/{ownerType}/{ownerId}/{bucket}/uploadToken:
    parameters:
      - $ref: '#/parameters/ownerType'
      - $ref: '#/parameters/ownerId'
      - $ref: '#/parameters/bucketId'
    get:
      summary: Issue a token for uploading files directly to S3
      tags:
        - S3
      responses:
        200:
          description: OK
          schema:
            $ref: '#/definitions/S3UploadToken'
        default:
          description: Could not issue token
          schema:
            $ref: '#/definitions/Feedback'

  # Permission grant information
  # based on resource services permission endpoint template
  /grant/Metadata/{permission}/{bucketId}:
    parameters:
      - $ref: '#/parameters/permission'
      - $ref: '#/parameters/bucketComposedId'
    get:
      tags:
        - Permissions
      summary: Test a permission on a specific resource
      responses:
        200:
          description: Allowed
        403:
          description: Denied
        400:
          description: Invalid composed bucket identifier or invalid permission

  /buckets/{ownerType}/{ownerId}/{bucket}/history:
    parameters:
      - $ref: '#/parameters/ownerType'
      - $ref: '#/parameters/ownerId'
      - $ref: '#/parameters/bucketId'
    get:
      summary: Get information on a bucket's history
      tags:
        - VersionControl
      responses:
        200:
          description: OK
          schema:
            $ref: '#/definitions/BucketHistory'
        default:
          description: Error retrieving bucket information
          schema:
            $ref: '#/definitions/Feedback'

securityDefinitions:
  bearer:
    type: apiKey
    name: Authorization
    in: header

parameters:
  bucketId:
    name: bucket
    in: path
    description: Bucket ID
    required: true
    type: string
  bucketPath:
    name: path
    in: path
    description: Path in the bucket
    required: true
    type: string
  ownerType:
    name: ownerType
    in: path
    description: The type of owner the bucket belongs to
    required: true
    type: string
    enum:
      - user
      - org
  ownerId:
    name: ownerId
    in: path
    description: The ID of the owner
    required: true
    type: string
  context:
    name: WETF-Context-Organisation
    in: header
    description: The organisation context
    required: false
    type: string
  propertyName:
    name: name
    in: path
    description: The name of the referenced property
    required: true
    type: string
  propertyValue:
    name: body
    in: body
    required: true
    description: Property value
    type: string
  toDetails:
    name: details
    in: query
    description: If bucket details should be returned instead of only the bucket identifier
    default: false
    type: boolean
  bucketComposedId:
    name: bucketId
    description: Identifier of the bucket including complete owner information
    in: path
    type: string
    required: true
  permission:
    name: permission
    description: The resource or application permission name
    in: path
    type: string
    required: true
  filter:
    name: '(filter)'
    in: query
    description: 'Filter by providing any bucket field als query parameter, use mongo syntax for value comparison. Examples: `properties.theme=xplanung-1599718912139`, `properties.tnitsDatasetCreationTime=gte:2015-08-16T21:37:05.505Z"`'
    required: false
    type: string
  sort:
    name: sort
    in: query
    description: 'The sort order of results. Example: `properties.tnitsDatasetCreationTime:asc`'
    required: false
    type: string

definitions:
  BucketInfo:
    type: object
    required:
      - id
    properties:
      id:
        description: Bucket identifier
        schema:
          $ref: '#/definitions/BucketIdent'
      # ...

  BucketDetail:
    allOf:
      - $ref: '#/definitions/BucketInfo'
      - type: object
        properties:
          created:
            description: The timestamp the bucket was created
            type: integer
          name:
            description: Human readable bucket name
            type: string
          lastModified:
            description: The timestramp the bucket content was last modified
            type: integer
          size:
            description: The accumulated files size in bytes
            type: integer
          fileCount:
            description: Number of files in the data set
            type: integer
          properties:
            description: Additional bucket properties, arbitrary Json object
            type: object
          # contexts:
          #   type: array
          #   items:
          #     type: string

  NewBucket:
    type: object
    properties:
      desiredId:
        description: The identifier of the new bucket
        type: string
      forceDesired:
        description: If only using the desired ID as ID for the new bucket is acceptable
        type: boolean
      name:
        description: A human readable bucket name
        type: string
      driver:
        description: The driver that should be used to create this bucket
        type: string
      properties:
        description: An arbitrary Json object with custom properties
        type: object

  FileInfo:
    type: object
    required:
      - isFolder
      - path
      - name
    properties:
      isFolder:
        description: If the resource is a folder (instead of a regular file)
        type: boolean
      accessUrl:
        description: URL the resource can be accessed/downloaded
        type: string
      path:
        description: Path in the bucket
        type: string
      name:
        description: Name without path
        type: string
      lastModified:
        description: Timestamp the file was last modified
        type: integer
      size:
        description: Size of the file
        type: integer

  PathInfo:
    allOf:
      - $ref: '#/definitions/FileInfo'
      - type: object
        properties:
          children:
            type: array
            items:
              # $ref: '#/definitions/PathInfo'
              $ref: '#/definitions/FileInfo' 

  BucketIdent:
    type: object
    description: Holds all information needed to identify a bucket
    required:
      - bucketId
    properties:
      bucketId:
        type: string
      userId:
        type: string
      orgId:
        type: string

  ChangeInfo:
    type: object
    description: Holds all information needed to identify a bucket
    properties:
      id:
        type: string
      shortText:
        type: string
      fullText:
        type: string
      author:
        type: string
      timestamp:
        type: string

  BucketHistory:
      type: array
      items:
        - $ref: '#/definitions/ChangeInfo'

  FileMetadata:
    type: object
    description: Metadata collected on a specific bucket file
    required:
      - path
    properties:
      path:
        type: string
        description: The file path in the bucket
      properties:
        type: object
        description: The file metadata properties

  S3UploadToken:
    type: object
    description: Token holding all information necessary to perform an upload to a bucket via S3
    required:
      - policy
      - accessKey
      - signature
    properties:
      policy:
        description: The policy document
        type: string
      accessKey:
        description: The AWS access key
        type: string
      signature:
        description: The token signature
        type: string
      baseKey:
        description: Fixed base key for uploaded files
        type: string
      bucketUrl:
        description: Base URL for accessing the S3 bucket
        type: string

  Feedback:
    type: object
    required:
      - code
      - message
      - error
    properties:
      code:
        type: integer
        format: int32
      message:
        type: string
      error:
        type: boolean

  CleanMetadataResult:
    type: object
    properties:
      keeping:
        type: array
        items:
          type: string
      removing:
        type: array
        items:
          type: string

