swagger: "2.0"
info:
  version: 2.0.0
  title: "BOXwise Pro RP REST API"
  description: | 
    The Remote Publisher API is the API used by BOXwise Pro to register and lookup remote publishers as well as allowing the remote publisher to upload/download files.
    
    The API is secured using a simple API Key Request Authorization scheme. Make sure the API Token is injected in the Headers of each request.
    
    **Admin Scoped Access**
    ```
    curl -X GET --header 'Accept: application/json' --header 'Authorization: Bearer [token]'
    ```
    
    **Publisher Scoped Access**
    For publishers using the API the security pattern is almost the same:

    ```
    curl -X GET --header 'Accept: application/json' --header 'Authorization: Publisher [token]'
    ```
    
    Make sure *token* is base64 encoded string of `key:secret` combined. 
    
    **License Scoped Access**
    For licenses (non-admin) using the API the security pattern is almost the same:

    ```
    curl -X GET --header 'Accept: application/json' --header 'Authorization: License [token]'
    ```

    Make sure token is base64 encoded string of `licenseid:apikey` combined.
  termsOfService: http://app.boxwise.nl/api/terms/
  contact:
    name: Trancon bv 
    email: f.vandenhoek@trancon.nl
    url: http://docs.boxwiseprorprestapi.apiary.io
  license:
    name: MIT
    url: http://github.com/gruntjs/grunt/blob/master/LICENSE-MIT
host: rp-httprest.app.boxwise.nl
basePath: /api
tags:
  - name: Licenses
    description: |
      Licenses refer to BOXwise Pro licenses. These are created here in order to register remote publishers to a license.
  - name: Files
    description: |
      Files refer to BOXwise Pro remote publisher files. These files are synced with the remote publisher.
  - name: Publishers
    description: |
      Publishers refer to BOXwise Pro Remote Publishers. These are API keys which can be used to upload files to BOXwise pro.
schemes:
  - https
consumes:
  - application/json; charset=utf-8
produces:
  - application/json; charset=utf-8
securityDefinitions:
  ApiKeyAuthorization:
    type: apiKey
    name: Authorization
    description: The API can only be used when you authorize the request using an API Key Token.
    in: header
  PublisherKeySecretAuthorization:
    type: apiKey
    name: Authorization
    description: The Files API be used when you authorize the request using an API Key/Secret Token based on a publisher key and secret. It will scope persmissions to this publisher.
    in: header
  LicenseKeySecretAuthorization:
    type: apiKey
    name: Authorization
    description: API Key for specific license that scopes permissions to this license
    in: header
security:
  - ApiKeyAuthorization: []
paths:
  /licenses:
    get:
      description: Find all registered BOXwise Pro licenses.
      operationId: findLicenses
      tags:
        - Licenses
      parameters:
        - name: name
          in: query
          description: License name to filter on.
          required: false
          type: string
        - name: isAuthorized
          in: query
          description: Filter on isAuthorized, omit to see all
          required: false
          type: boolean
        - name: limit
          in: query
          description: Maximum number of results to return.
          required: false
          type: integer
          format: int32
          default: 30
        - name: pagecursor
          in: query
          description: The next page starting from cursor.
          required: false
          type: string
      responses:
        200:
          description: license response
          schema:
            $ref: '#/definitions/Licenses'
        default:
          description: unexpected error
          schema:
            $ref: '#/definitions/Error'
    post:
      description: Creates a new license in the store if it does not already exist. Duplicates are not allowed. Returns an unauthorized API Key which can be used to perform subsequent requests (after it is approved).
      operationId: addLicense
      security: []
      tags:
        - Licenses
      parameters:
        - name: license
          in: body
          description: License to add to the store
          required: true
          schema:
            $ref: '#/definitions/NewLicense'
      responses:
        200:
          description: license response
          schema:
            $ref: '#/definitions/LicenseWithSecret'
        400:
          description: Bad Request/Validation error
          schema:
            $ref: '#/definitions/Error'
        409:
          description: Conflict/Already exists
          schema:
            $ref: '#/definitions/Error'
        default:
          description: unexpected error
          schema:
            $ref: '#/definitions/Error'
    put:
      description: Edits an existing license in the store.
      operationId: editLicense
      tags:
        - Licenses
      parameters:
        - name: license
          in: body
          description: License to edit in the store
          required: true
          schema:
            $ref: '#/definitions/License'
      responses:
        200:
          description: license response
          schema:
            $ref: '#/definitions/License'
        400:
          description: Bad Request/Validation error
          schema:
            $ref: '#/definitions/Error'
        default:
          description: unexpected error
          schema:
            $ref: '#/definitions/Error'
  /licenses/{licenseid}:
    delete:
      description: Deletes an existing license in the store and removes all it's publishers.
      operationId: deleteLicense
      tags:
        - Licenses
      parameters:
        - name: licenseid
          in: path
          description: License id of the license to delete from the store.
          required: true
          type: string
      responses:
        204:
          description: license deleted
        400:
          description: Bad Request/Validation error
          schema:
            $ref: '#/definitions/Error'
        default:
          description: unexpected error
          schema:
            $ref: '#/definitions/Error'
  /files:
    get:
      description: |
        Find all files registered for this license id.
      operationId: findFiles
      security:
        - ApiKeyAuthorization: []
          LicenseKeySecretAuthorization: []
          PublisherKeySecretAuthorization: []
      tags:
        - Files
      parameters:
        - name: licenseid
          in: query
          description: BOXwise Pro licenseid to filter on.
          required: false
          type: string
        - name: prefix
          in: query
          description: The prefix/folder to filter on.
          required: false
          type: string
          default: "/"
        - name: limit
          in: query
          description: Maximum number of results to return.
          required: false
          type: integer
          format: int32
          default: 30
      responses:
        200:
          description: files response
          schema:
            $ref: '#/definitions/Files'
        400:
          description: Bad Request/Validation error
          schema:
            $ref: '#/definitions/Error'
        default:
          description: unexpected error
          schema:
            $ref: '#/definitions/Error'
    post:
      description: |
        Upload a new file
      operationId: uploadFile
      security:
        - ApiKeyAuthorization: []
          LicenseKeySecretAuthorization: []
          PublisherKeySecretAuthorization: []
      tags:
        - Files
      parameters:
        - name: file
          in: body
          description: File to upload to boxwise.
          required: true
          schema:
            $ref: '#/definitions/UploadFile'
      responses:
        200:
          description: file response
          schema:
            $ref: '#/definitions/UploadedFileResponse'
        400:
          description: Bad Request/Validation error
          schema:
            $ref: '#/definitions/Error'
        default:
          description: unexpected error
          schema:
            $ref: '#/definitions/Error'
    delete:
      description: Deletes an existing file in the store.
      operationId: deleteFile
      security:
        - ApiKeyAuthorization: []
          LicenseKeySecretAuthorization: []
          PublisherKeySecretAuthorization: []
      tags:
        - Files
      parameters:
        - name: licenseid
          in: query
          description: BOXwise Pro licenseid to filter on.
          required: false
          type: string
          default: none
        - name: name
          in: query
          description: The name of the file.
          required: true
          type: string
        - name: prefix
          in: query
          description: The prefix/folder the files resides in.
          required: false
          type: string
          default: "/"
      responses:
        204:
          description: file deleted
        400:
          description: Bad Request/Validation error
          schema:
            $ref: '#/definitions/Error'
        default:
          description: unexpected error
          schema:
            $ref: '#/definitions/Error'
  /files-formdata:
    post:
      operationId: uploadFileThroughFormdata
      description: |
        Upload a new file through multipart/form-data protocol.
      security:
        - ApiKeyAuthorization: []
          LicenseKeySecretAuthorization: []
          PublisherKeySecretAuthorization: []
      consumes:
        - multipart/form-data
        - application/x-www-form-urlencoded
      tags:
        - Files
      parameters:
        - name: licenseid
          in: formData
          description: BOXwise Pro licenseid (not needed for publishers).
          required: false
          type: string
          default: none
        - name: file
          in: formData
          description: The uploaded file data.
          required: true
          type: file
        - name: filename
          in: formData
          description: The name of the file.
          required: true
          type: string
        - name: overwrite
          in: formData
          description: Overwriteif exists
          required: true
          type: boolean
          default: true
        - name: prefix
          in: formData
          description: The prefix/folder to upload file to
          required: false
          type: string
          default: "/"
      responses:
        200:
          description: file response
          schema:
            $ref: '#/definitions/UploadedFileResponse'
        400:
          description: Bad Request/Validation error
          schema:
            $ref: '#/definitions/Error'
        default:
          description: unexpected error
          schema:
            $ref: '#/definitions/Error'
  /files/{licenseid}/download:
    get:
      description: Download a file from the store
      security:
        - ApiKeyAuthorization: []
          LicenseKeySecretAuthorization: []
      operationId: downloadFile
      produces: ['application/octet-stream']
      tags:
        - Files
      parameters:
        - name: licenseid
          in: path
          description: BOXwise Pro licenseid to filter on.
          required: true
          type: string
          default: none
        - name: filepath
          in: query
          description: The name and prefix of the file combined (e.g. /in/010203/test.dat).
          required: true
          type: string
          default: none
      responses:
        200:
          description: The file download
          schema:
            type: file
        400:
          description: Bad Request/Validation error
          schema:
            $ref: '#/definitions/Error'
        default:
          description: unexpected error
          schema:
            $ref: '#/definitions/Error'
  /publishers:
    get:
      description: |
        Returns all publishers registered for this license id.
      security:
        - ApiKeyAuthorization: []
          LicenseKeySecretAuthorization: []
      operationId: findPublishers
      tags:
        - Publishers
      parameters:
        - name: licenseid
          in: query
          description: BOXwise Pro licenseid to filter on.
          required: true
          type: string
          default: none
        - name: limit
          in: query
          description: Maximum number of results to return.
          required: false
          type: integer
          format: int32
          default: 30
        - name: pagecursor
          in: query
          description: The next page starting from cursor.
          required: false
          type: string
      responses:
        200:
          description: publishers response
          schema:
            $ref: '#/definitions/Publishers'
        400:
          description: Bad Request/Validation error
          schema:
            $ref: '#/definitions/Error'
        default:
          description: unexpected error
          schema:
            $ref: '#/definitions/Error'
    post:
      operationId: addPublisher
      description: Creates a new publisher in the store. Duplicates are not allowed. The publisher key is checked against all other keys registered regardless under which licenseid they are registered.
      security:
        - ApiKeyAuthorization: []
          LicenseKeySecretAuthorization: []
      tags:
        - Publishers
      parameters:
        - name: publisher
          in: body
          description: Publisher to add to the store.
          required: true
          schema:
            $ref: '#/definitions/NewPublisher'
      responses:
        200:
          description: publisher response
          schema:
            $ref: '#/definitions/Publisher'
        400:
          description: Bad Request/Validation error
          schema:
            $ref: '#/definitions/Error'
        default:
          description: unexpected error
          schema:
            $ref: '#/definitions/Error'
  /{licenseid}/publishers/{key}:
    get:
      description: Returns a publisher based on the key.
      security:
        - ApiKeyAuthorization: []
          LicenseKeySecretAuthorization: []
      operationId: getPublisherByKey
      tags:
        - Publishers
      parameters:
        - name: key
          in: path
          description: Key of publisher to fetch.
          required: true
          type: string
        - name: licenseid
          in: path
          description: LicenseId of the publisher.
          required: true
          type: string
      responses:
        200:
          description: publisher response
          schema:
            $ref: '#/definitions/Publisher'
        400:
          description: Bad Request/Validation error
          schema:
            $ref: '#/definitions/Error'
        default:
          description: unexpected error
          schema:
            $ref: '#/definitions/Error'
    put: 
      description: |
        Updates publisher name and expiration date.
        The licenseid ensures a publisher from antoher license cannot edited.
      security:
        - ApiKeyAuthorization: []
          LicenseKeySecretAuthorization: []
      operationId: updatePublisherByKey
      tags:
        - Publishers
      parameters:
        - name: key
          in: path
          description: Key of publisher to update.
          required: true
          type: string
        - name: licenseid
          in: path
          description: BOXwise Pro licenseid of the publisher.
          required: true
          type: string
        - name: publisher
          in: body
          description: Publisher to update.
          required: true
          schema:
            $ref: '#/definitions/EditPublisher'  
      responses:
        200:
          description: publisher response
          schema:
            $ref: '#/definitions/Publisher'
        400:
          description: Bad Request/Validation error
          schema:
            $ref: '#/definitions/Error'
        default:
          description: unexpected error
          schema:
            $ref: '#/definitions/Error'
    delete:
      description: |
        Deletes a single publisher based on the key supplied.
        The licenseid ensures a publisher from antoher license cannot be deleted.
      security:
        - ApiKeyAuthorization: []
          LicenseKeySecretAuthorization: []
      operationId: deletePublisher
      tags:
        - Publishers
      parameters:
        - name: key
          in: path
          description: Key of publishers to delete.
          required: true
          type: string
        - name: licenseid
          in: path
          description: BOXwise Pro licenseid of the publisher.
          required: true
          type: string
      responses:
        204:
          description: publishers deleted
        400:
          description: Bad Request/Validation error
          schema:
            $ref: '#/definitions/Error'
        default:
          description: unexpected error
          schema:
            $ref: '#/definitions/Error'
definitions:
  PagedResult:
    properties:
      nextcursor:
        type: string
  Licenses:
    allOf:
      - $ref: '#/definitions/PagedResult'
      - type: object
        properties:
          result:
            type: array
            items:
              $ref: '#/definitions/License'
    example:
      nextcursor: kwqjhekjeekwq32u4hfgde==
      result: 
        - name: "Customer X"
          licenseid: 112
          timeCreated: "1985-04-12T23:20:50.52Z"
        - name: "Customer Y"
          licenseid: 113
          timeCreated: "1985-04-12T23:20:50.52Z"
  License:
    required:
      - licenseid
      - name
    properties:
      licenseid:
        type: string
      name:
        type: string
      isAuthorized:
        type: boolean
      timeCreated:
        type: string
        format: date-time
    example:
      licenseid: 122
      name: "Customer X"
      isAuthorized: false
      timeCreated: "1985-04-12T23:20:50.52Z"
  LicenseWithSecret:
    allOf:
      - $ref: '#/definitions/License'
      - type: object
        properties:
          apiKey:
            type: string
    required:
      - apiKey
    example:
      licenseid: 122
      name: "Customer X"
      apiKey: "dkjd238o7rgkjbdewqjkqrewjkhrekujg"
      isAuthorized: false
      timeCreated: "1985-04-12T23:20:50.52Z"
  NewLicense:
    required:
      - licenseid
      - name
      - secret
    properties:
      licenseid:
        type: string
      secret:
        type: string
      name:
        type: string
    example:
      licenseid: "122"
      name: "Customer X"
      secret: "secret"
  Publishers:
    allOf:
      - $ref: '#/definitions/PagedResult'
      - type: object
        properties:
          result:
            type: array
            items:
              $ref: '#/definitions/Publisher'
    example:
      nextcursor: kwqjhewekjeekwq32u4hfgde==
      result: 
        - licenseid: "122"
          key: "kdqjwk8q3e47qjdnbeqhwg"
          secret: "qwjkdhgqjkhgr2fbrfjhrlqwkjfb378fgblq3fkjwqmnfbrbq"
          name: "HL - Hospital Logistics #1"
          timeCreated: "1985-04-12T23:20:50.52Z"
        - licenseid: "122"
          key: "wfoiquyr4kjfrehwfhjkgqr"
          secret: "welkjfgqjwhfbi348irbfqkwj34qergewrgkjrehwfgjkhbre"
          name: "HL - Hospital Logistics #2"
          timeCreated: "1985-04-12T23:20:50.52Z"
  Publisher:
    allOf:
      - $ref: '#/definitions/NewPublisher'
      - type: object
        properties:
          key:
            type: string
          secret:
            type: string
          expiresAt:
            type: string
            format: date-time
          timeCreated:
            type: string
            format: date-time
    required:
      - key
      - secret
      - licenseid
    example:
      licenseid: "122"
      key: "kdqjwk8q3e47qjdnbeqhwg"
      secret: "qwjkdhgqjkhgr2fbrfjhrlqwkjfb378fgblq3fkjwqmnfbrbq"
      name: "HL - Hospital Logistics"
      expiresAt: "2020-04-12T23:20:50.52Z"
      timeCreated: "1985-04-12T23:20:50.52Z"
  NewPublisher:
    required:
      - licenseid
      - name
    properties:
      licenseid:
        type: string
      name:
        type: string
    example:
      licenseid: "122"
      name: "HL - Hospital Logistics"
  EditPublisher:
    required:
      - expiresAt
      - name
    properties:
      name:
        type: string
      expiresAt:
        type: string
        format: date-time
    example:
      expiresAt:  "1985-04-12T23:20:50.52Z"
      name: "HL - Hospital Logistics"
  Files:
    allOf:
      - $ref: '#/definitions/PagedResult'
      - type: object
        properties:
          result:
            type: array
            items:
              $ref: '#/definitions/File'
    example:
      result: 
        - name: "meta.dat"
          size: 115
          timeCreated: "1985-04-12T23:20:50.52Z"
        - name: "prodidx.dat"
          size: 3343
          timeCreated: "1985-04-12T23:20:50.52Z"
          updated: "1985-04-12T23:20:50.52Z"
      nextcursor: "ReferenceToNextPage"
  File:
    required:
      - name
      - size
    properties:
      name:
        type: string
      size:
        type: integer
        format: int64
      timeCreated:
        type: string
        format: date-time
      updated:
        type: string
        format: date-time
    example:
      name: "meta.dat"
      size: 115
      timeCreated: "1985-04-12T23:20:50.52Z"
      updated: "1985-04-12T23:20:50.52Z"
  UploadFile:
    required:
      - filename
      - file
      - overwrite
    properties:
      licenseid:
        type: string
        description: license to upload file under. Only needed with ApikeyAuthorization
      filename:
        type: string
        description: name of the file to upload it under to boxwise
      file:
        type: string
        description: file contents of the file base64 encoded
        format: byte
      overwrite:
        type: boolean
        description: wether to overwrite file if it already exists
      prefix:
        type: string
    example:
      filename: "meta.dat"
      file: "ZmlsZTtjb250ZW50czsK"
      overwrite: false
      prefix: /ex
      licenseid: test-lic
  UploadedFileResponse:
    required:
      - name
      - size
      - licenseid
    allOf:
      - $ref: '#/definitions/File'
      - type: object
        properties:
          licenseid:
            type: string
    example:
      licenseid: "12"
      name: "meta.dat"
      size: 115
      timeCreated: "1985-04-12T23:20:50.52Z"
      updated: "1985-04-12T23:20:50.52Z"
  Error:
    required:
      - statusCode
      - error
    properties:
      statusCode:
        type: integer
        format: int32
      error:
        type: string
      message:
        type: string
    example:
      statusCode: 500
      error: "Internal Server Erorr"
      message: "An unhandled Internal Server Erorr occurred"