openapi: 3.0.0
servers:
# Added by API Auto Mocking Plugin
  - description: BIMcloud Manager
    url: https://bimcloud.graphisoft.com
  - description: BIMcoud Blob server
    url: https://blobserver.graphisoft.com
info:
  description: |
    BIMcloud API specifiaction.
    See the provided example for detailed information.
  version: "1.0.0"
  title: BIMcloud API 2020.2 (alpha release)
tags:
  - name: PortalServer
    description: |
      User login, session, ticket handling and resource management APIs
  - name: BlobServer
    description: |
      Blob server login/authentication APIs and file management APIs
paths:
  # PORTAL SERVER SESSION APIS

  /management/client/create-session:
    post:
      tags:
        - PortalServer
      description: Creates a new session for callee.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSessionRequest'
      responses:
        200:
          description: 'Creates a new session'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateSessionResponse'
        430:
          description: 'Request errors'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PortalServerError'
        503:
          description: 'Server unavailable, retry the request later.'

  /management/client/ping-session:
    post:
      tags:
        - PortalServer
      description: Pings an already opened session to prevent expiration.
      parameters:
        - in: query
          name: session-id
          schema:
            type: string
          description: The ID of the session to keep alive
          example: d290f1ee-6c54-4b01-90e6-d701748f0851
      responses:
        200:
          description: 'Session lifetime extended.'
          content:
            application/json:
              schema:
                type: object
                properties:
                  user-id:
                    type: string
                    example: d290f1ee-6c54-4b01-90e6-d701748f0852
                    description: The ID of the user whose session got extended
        430:
          description: 'Request errors'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PortalServerError'
        503:
          description: 'Server unavailable, retry the request later.'

  /management/client/close-session:
    post:
      tags:
        - PortalServer
      description: Closes the session.
      parameters:
        - in: query
          name: session-id
          schema:
            type: string
          description: The ID of the session to close
          example: d290f1ee-6c54-4b01-90e6-d701748f0851
      responses:
        200:
          description: Session has been successfully closed, if session with the provided id was found
        503:
          description: 'Server unavailable, retry the request later.'

  /management/client/ticket-generator/get-ticket:
    post:
      tags:
        - PortalServer
      description: |
        Requests a ticket. The ticket is required for file operations.
      parameters:
        - in: query
          name: session-id
          schema:
            type: string
          description: session-id returned by /management/client/create-session
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetTicketRequest'
      responses:
        200:
          description: |
            Successful ticket request. When input parameter `format` is `base64`, the resonse content type will be
            `application/json`, else it will be `application/octet-stream`. The preferred format is `base64`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetTicketResponseBase64'
            application/octet-stream:
              schema:
                $ref: '#/components/schemas/GetTicketResponseLengthPrefixedBuffer'
        430:
          description: 'Request errors'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PortalServerError'
        503:
          description: 'Server unavailable, retry the request later.'

  # PORTAL SERVER RESOURCE MANAGEMENT APIS

  /management/client/get-resource:
    get:
      tags:
        - PortalServer
      description: |
        Request a single resource by ID.
      parameters:
        - in: query
          name: session-id
          schema:
            type: string
          description: session-id returned by /management/client/create-session
          example: d290f1ee-6c54-4b01-90e6-d701748f0851
        - in: query
          name: resource-id
          schema:
            type: string
          description: The ID of the requested resource
          example: 8b4989f6-8c31-12f9-1ae0-75b1da4142fc
      responses:
        200:
          description: Requested resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Resource'
        430:
          description: 'Request errors'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PortalServerError'
        503:
          description: 'Server unavailable, retry the request later.'

  /management/client/get-resources-by-criterion:
    post:
      tags:
        - PortalServer
      description: |
        Requests an array of resources that match the supplied criterion object
      parameters:
        - in: query
          name: session-id
          schema:
            type: string
          description: session-id returned by /management/client/create-session
          example: d290f1ee-6c54-4b01-90e6-d701748f0851
      requestBody:
        description: The criterion object
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CriterionObject'
      responses:
        200:
          description: Successful get-resource request
          content:
            application/json:
              schema:
                type: array
                items:
                    $ref: '#/components/schemas/Resource'
        430:
          description: 'Request errors'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PortalServerError'
        503:
          description: 'Server unavailable, retry the request later.'

  /management/client/insert-resource-group:
    post:
      tags:
        - PortalServer
      description: |
        Creates a resrource group (folder) entity in the resource tree based on the supplied parameters
      parameters:
        - in: query
          name: session-id
          schema:
            type: string
          description: session-id returned by /management/client/create-session
          example: d290f1ee-6c54-4b01-90e6-d701748f0851
        - in: query
          name: parent-id
          schema:
            type: string
          description: The ID of the parent resource group entity. The root entity's ID is `projectRoot`.
          example: 8b4989f6-8c31-12f9-1ae0-75b1da4142fd
      requestBody:
        description: Resource group description
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  example: folder2
                  description: The name of the resource group to be created
                type:
                  type: string
                  pattern: resourceGroup
                  example: resourceGroup
                  description: The type of the resource to be created.
      responses:
        200:
          description: Successful insert-resource-group request
          content:
            application/json:
              schema:
                type: string
                example: 8b4989f6-8c31-12f9-1ae0-75b1da4142fc
                description: The ID of the created resource group
        430:
          description: 'Request errors'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PortalServerError'
        503:
          description: 'Server unavailable, retry the request later.'

  /management/client/delete-resource-group:
    delete:
      tags:
        - PortalServer
      description: |
        Deletes an **empty** resrource group (folder) entity from the resource tree by ID.
      parameters:
        - in: query
          name: session-id
          schema:
            type: string
          description: session-id returned by /management/client/create-session
          example: d290f1ee-6c54-4b01-90e6-d701748f0851
        - in: query
          name: resource-id
          schema:
            type: string
          description: The ID of the resource group entity to be deleted.
          example: 8b4989f6-8c31-12f9-1ae0-75b1da4142fc
      responses:
        200:
          description: Successful delete-resource-group request
          content:
            application/json:
              schema:
                type: object
                example: {}
                description: Empty object.
        430:
          description: 'Request errors'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PortalServerError'
        503:
          description: 'Server unavailable, retry the request later.'

  /management/client/delete-resources-by-id-list:
    post:
      tags:
        - PortalServer
      description: |
        Starts a job to delete resources by specified identifiers. The job deletes folders recursively.
      parameters:
        - in: query
          name: session-id
          schema:
            type: string
          description: session-id returned by /management/client/create-session
          example: d290f1ee-6c54-4b01-90e6-d701748f0851
      responses:
        200:
          description: Job of type *destroyResources* representing the on-giong operation to delete resources.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Job'
        430:
          description: 'Request errors'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PortalServerError'
        503:
          description: 'Server unavailable, retry the request later.'

  /management/client/update-blob:
    put:
      tags:
        - PortalServer
      description: |
        Updates a blob entity identified by id.
      parameters:
        - in: query
          name: session-id
          schema:
            type: string
          description: session-id returned by /management/client/create-session
          example: d290f1ee-6c54-4b01-90e6-d701748f0851
      requestBody:
        description: Blob data
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: string
                  example: d290f1ee-6c54-4b01-90e6-d701748f0851
                  description: The id of the blob to be updated
                name:
                  type: string
                  example: folder2
                  description: The new name of the blob
                type:
                  type: string
                  pattern: blob
                  example: blob
                  description: The type of the resource to be created.
      responses:
        200:
          description: Successful update-blob request
          content:
            application/json:
              schema:
                type: object
                example: {}
                description: Empty object.
        430:
          description: 'Request errors'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PortalServerError'
        503:
          description: 'Server unavailable, retry the request later.'

  /management/client/update-blob-parent:
    put:
      tags:
        - PortalServer
      description: |
        Updates parent of a Blob. Baiscally moves it to a different directory.
      parameters:
        - in: query
          name: session-id
          schema:
            type: string
          description: session-id returned by /management/client/create-session
          example: d290f1ee-6c54-4b01-90e6-d701748f0851
        - in: query
          name: blob-id
          schema:
            type: string
            format: uuid
          example: 4D7C7BB1-7AEF-4CD2-9146-0286561D6F85
          description: The ID of the blob to update
      requestBody:
        description: Request body. Use one of its properties to modify parent by path or by id.
        content:
          application/json:
            schema:
              type: object
              properties:
                parentPath:
                  type: string
                  example: Project Root/folder2
                  nullable: true
                  description: New parent folder's path.
                parentId:
                  type: string
                  format: uuid
                  nullable: true
                  description: New parent folder's id.
      responses:
        200:
          description: Successful update.
          content:
            application/json:
              schema:
                type: boolean
                example: true
                description: Parent has been updated or stayed the same.
        430:
          description: 'Request errors'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PortalServerError'
        503:
          description: 'Server unavailable, retry the request later.'

  /management/client/get-blob-changes-for-sync:
    put:
      tags:
        - PortalServer
      description: |
        Gets blob changes of a specified resource group from a given revision number.

        Blob Server side changes are accessible for helping synchronization scenarios.
          We support a simple polling mechanism for that, by utilizing the get-blob-changes-for-sync API.
          Changesets are separated by revisions, and synchronization always start at revision 0.

        Revision 0 is a special case, it gives all content in the given folder in its result's "created" array field.
          After revision 0 the next set of changes are are accessible by using the last knonw changeset's "endRevision" value in the request's "fromRevison" parameter.
      parameters:
        - in: query
          name: session-id
          schema:
            type: string
          description: session-id returned by /management/client/create-session
          example: d290f1ee-6c54-4b01-90e6-d701748f0851
      requestBody:
        description: |
          Use either resourceGroupId or path as a parameter but sending both is not necessary.
        content:
            application/json:
              schema:
                type: object
                properties:
                  resourceGroupId:
                    type: string
                    example: d290f1ee-6c54-4b01-90e6-d701748f0852
                    description: The ID of the resource group
                    nullable: true
                  path:
                    type: string
                    example: Project Root/folder
                    description: The path of the resource group
                    nullable: true
                  fromRevision:
                    type: number
                    example: 1
                    description: The revision number to get the changes from
      responses:
        200:
          description: Successful get-blob-changes-for-sync request
          content:
            application/json:
              schema:
                type: object
                properties:
                  endRevision:
                    type: number
                    example: 1
                    description: Maximum of the received revisions
                  created:
                    type: array
                    items:
                      $ref: '#/components/schemas/GetBlobChangesForSyncResponseCreatedOrUpdatedObject'
                  updated:
                    type: array
                    items:
                      $ref: '#/components/schemas/GetBlobChangesForSyncResponseCreatedOrUpdatedObject'
                  deleted:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          format: uuid
                        path:
                          type: string
                          example: Project Root/folder1
        430:
          description: |
            Request errors.

            Error code 9 is a special case there and it means Revision Obsoleted Error.
              This happen when the underlying content database has been replaced to another one under the hood,
              for example after restoring backups.

            When this happens, synchronization flow should reset, and should get started from revision 0.
              The first request from revision zero will contain the whole content of the folder in the new database in the "created" array field of the API result.
              The client should use this as a basis of a new synchronization cycle, and should reinitializa its content according the content of the "created" array.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PortalServerError'
        503:
          description: 'Server unavailable, retry the request later.'

  /management/client/delete-blob:
    delete:
      tags:
        - PortalServer
      description: |
        Deletes a file entity from the resource tree by ID.
      parameters:
        - in: query
          name: session-id
          schema:
            type: string
          description: session-id returned by /management/client/create-session
          example: d290f1ee-6c54-4b01-90e6-d701748f0851
        - in: query
          name: resource-id
          schema:
            type: string
          description: The ID of the blob entity to be deleted.
          example: 33E36B98-2758-4C17-83E5-69E93B8B87CB
      responses:
        200:
          description: Successful delete-blob request
          content:
            application/json:
              schema:
                type: object
                example: {}
                description: Empty object.
        430:
          description: 'Request errors'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PortalServerError'
        503:
          description: 'Server unavailable, retry the request later.'

  /management/client/get-inherited-default-blob-server-id:
    get:
      tags:
        - PortalServer
      description: |
        Requests the inherited default blob server ID of a specified resourceGroup (folder) entitiy
      parameters:
        - in: query
          name: session-id
          schema:
            type: string
          description: session-id returned by /management/client/create-session
          example: d290f1ee-6c54-4b01-90e6-d701748f0851
        - in: query
          name: resource-group-id
          schema:
            type: string
          description: The ID of the resource group entity. The root entity's ID is "projectRoot".
          example: 8b4989f6-8c31-12f9-1ae0-75b1da4142fc
      responses:
        200:
          description: The ID of the inherited default blob server associated with the supplied resrouceGroup.
          content:
            application/json:
              schema:
                type: string
                example: d290f1ee-6c54-4b01-90e6-d701748f0853
                format: uuid
                description: The ID of inherited default host server
        430:
          description: 'Request errors'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PortalServerError'
        503:
          description: 'Server unavailable, retry the request later.'

  # PORTAL SERVER JOB API

  /management/client/get-job:
    get:
      tags:
        - PortalServer
      description: |
        Request a single job by ID.
      parameters:
        - in: query
          name: session-id
          schema:
            type: string
          description: session-id returned by /management/client/create-session
          example: d290f1ee-6c54-4b01-90e6-d701748f0851
        - in: query
          name: job-id
          schema:
            type: string
          description: The ID of the requested job
          example: 8b4989f6-8c31-12f9-1ae0-75b1da4142fc
      responses:
        200:
          description: Result Job.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Job'
        430:
          description: |
            Common request errors.

            Only meaningful error code there is 6 (EntityNotFoundError) which means Job has been removed the system entirely.
            If a job completed or failed, it will stay in the database for a few minutes, but eventually it will get deleted for good.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PortalServerError'
        503:
          description: 'Server unavailable, retry the request later.'

  /management/client/abort-job:
    post:
      tags:
        - PortalServer
      description: |
        Request to abort a running job.
      parameters:
        - in: query
          name: session-id
          schema:
            type: string
          description: session-id returned by /management/client/create-session
          example: d290f1ee-6c54-4b01-90e6-d701748f0851
        - in: query
          name: job-id
          schema:
            type: string
          description: The ID of the job
          example: 8b4989f6-8c31-12f9-1ae0-75b1da4142fc
      responses:
        200:
          description: |
            Responds with *true* if the job was running and was abortable and has been aborted successfully.

            Responds with *false* if it hasn't.
          content:
            application/json:
              schema:
                type: boolean
        430:
          description: |
            Common request errors.

            Only meaningful error code there is 6 (EntityNotFoundError) which means Job has been removed the system entirely.
            If a job completed or failed, it will stay in the database for a few minutes, but eventually it will get deleted for good.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PortalServerError'
        503:
          description: 'Server unavailable, retry the request later.'

  # BLOB SERVER SESSION APIS

  /session-service/1.0/create-session:
    post:
      tags:
        - BlobServer
      description: |
        Creates a session on the BIMcloud Blob Server. Requires a ticket generated by the BIMcloud Portal server on
        path `/management/client/ticket-generator/get-ticket`.
      requestBody:
        content:
          application/vnd.graphisoft.teamwork.session-service-1.0.authentication-request-1.0+json:
            schema:
              $ref: '#/components/schemas/BlobServerAuthenticationRequest'
      responses:
        200:
          description: Successful blob server create-session request
          content:
            application/vnd.graphisoft.teamwork.session-service-1.0.session-1.0+json:
              schema:
                type: object
                properties:
                  data-content-type:
                    type: string
                    example: application/vnd.graphisoft.teamwork.session-service-1.0.session-1.0+json
                  data:
                    $ref: '#/components/schemas/BlobServerSessionResponse'
        401:
          description: |
            The supplied ticket is incorrect. The returned error will be:
            - `3` `AuthenticationFailed`
          content:
            application/vnd.graphisoft.teamwork.session-service-1.0.session-1.0+json:
              schema:
                type: object
                properties:
                  data-content-type:
                    type: string
                    example: application/vnd.graphisoft.teamwork.session-service-1.0.session-1.0+json
                  data:
                    $ref: '#/components/schemas/BlobServerSessionResponse'
        430:
          description: Unsuccessful blob server create-session request
          content:
            application/vnd.graphisoft.teamwork.generic-service-1.0.detailed-error-1.0+json:
              schema:
                $ref: '#/components/schemas/BlobServerDetailedError'

  /session-service/1.0/get-session:
    get:
      tags:
        - BlobServer
      description: |
        Requests information about an already existing session by ID.
      parameters:
        - in: query
          name: session-id
          schema:
            type: string
          example: 5cf6ee792cdf05e1ba2b6325c41a5f10
          description: The ID of the session
      responses:
        200:
          description: Successful blob server get-session request
          content:
            application/vnd.graphisoft.teamwork.session-service-1.0.session-1.0+json:
              schema:
                type: object
                properties:
                  data-content-type:
                    type: string
                    example: application/vnd.graphisoft.teamwork.session-service-1.0.session-1.0+json
                  data:
                    $ref: '#/components/schemas/BlobServerSessionResponse'
        430:
          description: Unsuccessful blob server get-session request
          content:
            application/vnd.graphisoft.teamwork.generic-service-1.0.detailed-error-1.0+json:
              schema:
                $ref: '#/components/schemas/BlobServerDetailedError'

  /session-service/1.0/close-session:
    post:
      tags:
        - BlobServer
      description: |
        Closes the session on the BIMcloud blob server.
      parameters:
        - in: query
          name: session-id
          schema:
            type: string
          example: 5cf6ee792cdf05e1ba2b6325c41a5f10
          description: the ID of the session to close
      responses:
        200:
          description: Successful blob server close-session request
        430:
          description: Unsuccessful blob server close-session request
          content:
            application/vnd.graphisoft.teamwork.generic-service-1.0.detailed-error-1.0+json:
              schema:
                $ref: '#/components/schemas/BlobServerDetailedError'

  # BLOB STORE BLOB SERVER UPLOAD APIS

  /blob-store-service/1.0/begin-batch-upload:
    post:
      tags:
        - BlobServer
      description: |
        Creates a batch upload session.
      parameters:
        - in: query
          name: session-id
          schema:
            type: string
          example: 5cf6ee792cdf05e1ba2b6325c41a5f10
          description: The ID of the blob server session returned by /session-service/1.0/create-session

        - in: query
          name: description
          schema:
            type: string
          example: This is the description of the batch upload session.
          description: The description of the batch being uploaded. Any URL encoded text.
      responses:
        200:
          description: Batch upload session successfully created.
          content:
            application/vnd.graphisoft.teamwork.blob-store-service-1.0.batch-upload-session-1.0+json:
              schema:
                type: object
                properties:
                    data-content-type:
                      type: string
                      example: application/vnd.graphisoft.teamwork.blob-store-service-1.0.batch-upload-session-1.0+json
                    data:
                      $ref: '#/components/schemas/BlobServerBatchUploadSessionResponse'
        430:
          description: Unsuccessful blob server begin-batch-upload request
          content:
            application/vnd.graphisoft.teamwork.generic-service-1.0.detailed-error-1.0+json:
              schema:
                $ref: '#/components/schemas/BlobServerDetailedError'

  /blob-store-service/1.0/begin-upload:
    post:
      tags:
        - BlobServer
      description: |
        Creates an upload session.
      parameters:
        - in: query
          name: session-id
          schema:
            type: string
          example: 5cf6ee792cdf05e1ba2b6325c41a5f10
          description: The ID of the blob server session returned by /session-service/1.0/create-session
        - in: query
          name: blob-name
          schema:
            type: string
            format: path
          example: /folder/file.png
          description: The full path of the file to be uploaded
        - in: query
          name: namespace-name
          schema:
            type: string
            format: uuid
          example: 832DBA54-7E0B-463C-B0EF-DB65DAB25745
          description: The namespace-name returned by begin-batch-upload
      responses:
        200:
          description: Upload session successfully created.
          content:
            application/vnd.graphisoft.teamwork.blob-store-service-1.0.upload-session-1.0+json:
              schema:
                type: object
                properties:
                  data-content-type:
                    type: string
                    example: application/vnd.graphisoft.teamwork.blob-store-service-1.0.upload-session-1.0+json
                  data:
                    $ref: '#/components/schemas/BlobServerUploadSessionResponse'
        430:
          description: Unsuccessful blob server begin-upload request
          content:
            application/vnd.graphisoft.teamwork.generic-service-1.0.detailed-error-1.0+json:
              schema:
                $ref: '#/components/schemas/BlobServerDetailedError'

  /blob-store-service/1.0/put-blob-content-part:
    post:
      tags:
        - BlobServer
      description: |
        Uploads a blob chunk.
      parameters:
        - in: query
          name: session-id
          schema:
            type: string
          example: 5cf6ee792cdf05e1ba2b6325c41a5f10
          description: The ID of the blob server session returned by /session-service/1.0/create-session

        - in: query
          name: upload-session-id
          schema:
            type: string
            format: uuid
          example: 6894B3DD-74FE-48AE-BD5E-266861659B13
          description: The ID of the upload-session this blob chunk belongs to

        - in: query
          name: offset
          schema:
            type: integer
          example: "0"
          description: The offset of the chunk being uploaded from the beginning of the blob in bytes

        - in: query
          name: length
          schema:
            type: integer
          example: 484173
          description: The size of the chunk being uploaded.
      requestBody:
        description: The actual chunk to be uploaded
        content:
          multipart/form-data:
            schema:
              type: string
              format: binary
              example: <binary data>
      responses:
        200:
          description: Chunk successfully uploaded.
          content:
            application/vnd.graphisoft.teamwork.blob-store-service-1.0.upload-session-1.0+json:
              schema:
                type: object
                properties:
                  data-content-type:
                    type: string
                    example: application/vnd.graphisoft.teamwork.blob-store-service-1.0.upload-session-1.0+json
                  data:
                    $ref: '#/components/schemas/BlobServerUploadSessionResponse'
        430:
          description: Unsuccessful blob server put-blob-content-part request
          content:
            application/vnd.graphisoft.teamwork.generic-service-1.0.detailed-error-1.0+json:
              schema:
                $ref: '#/components/schemas/BlobServerDetailedError'

  /blob-store-service/1.0/commit-upload:
    post:
      tags:
        - BlobServer
      description: |
        Commits a single blob upload session.

        **IMPORTANT** The blob-id in the response to this request will be a temporary ID.

        The final ID will get assigned when /blob-store-service/1.0/commit-batch-upload is called by the client!
      parameters:
        - in: query
          name: session-id
          schema:
            type: string
          example: 5cf6ee792cdf05e1ba2b6325c41a5f10
          description: The ID of the blob server session returned by /session-service/1.0/create-session
        - in: query
          name: upload-session-id
          schema:
            type: string
            format: uuid
          example: 6894B3DD-74FE-48AE-BD5E-266861659B13
          description: The ID of the upload-session to be committed
      responses:
        200:
          description: Upload session successfully committed.
          content:
            application/vnd.graphisoft.teamwork.blob-store-service-1.0.blob-metadata-1.0+json:
              schema:
                type: object
                properties:
                  data-content-type:
                    type: string
                    example: application/vnd.graphisoft.teamwork.blob-store-service-1.0.blob-metadata-1.0+json
                  data:
                    $ref: '#/components/schemas/BlobServerBlobMetadataResponse'
        430:
          description: Upload session could not be committed.
          content:
            application/vnd.graphisoft.teamwork.generic-service-1.0.detailed-error-1.0+json:
              schema:
                $ref: '#/components/schemas/BlobServerDetailedError'

  /blob-store-service/1.0/commit-batch-upload:
    post:
      tags:
        - BlobServer
      description: |
        Commits a batch upload session.

        **IMPORTANT** The final IDs of the blobs uploaded in this session will be available in the response body of this request.
      parameters:
        - in: query
          name: session-id
          schema:
            type: string
          example: 5cf6ee792cdf05e1ba2b6325c41a5f10
          description: The ID of the blob server session returned by /session-service/1.0/create-session
        - in: query
          name: batch-upload-session-id
          schema:
            type: string
            format: uuid
          example: 832DBA54-7E0B-463C-B0EF-DB65DAB25745
          description: The ID of the batch-upload-session to be committed
        - in: query
          name: conflict-behavior
          schema:
            type: string
            pattern: overwrite|fail
          example: overwrite
          description: |
            The desired conflict resolution method.
            When the target blob already exists will either overwrite the existing blob or throw an error.

            The allowed values are `overwrite` and `fail`.
      responses:
        200:
          description: Batch upload session successfully committed.
          content:
            application/vnd.graphisoft.teamwork.blob-store-service-1.0.blob-metadata-1.0-list+json:
              schema:
                type: object
                properties:
                  data-content-type:
                    type: string
                    example: application/vnd.graphisoft.teamwork.blob-store-service-1.0.blob-metadata-1.0-list+json
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/BlobServerBlobMetadataResponse'

        430:
          description: Batch upload session could not be committed.
          content:
            application/vnd.graphisoft.teamwork.generic-service-1.0.detailed-error-1.0+json:
              schema:
                $ref: '#/components/schemas/BlobServerDetailedError'

  /blob-store-service/1.0/get-blob-content:
    get:
      tags:
        - BlobServer
      description: |
        Downloads a single file from the BIMcloud Blob Server
      parameters:
        - in: query
          name: session-id
          schema:
            type: string
          example: 5cf6ee792cdf05e1ba2b6325c41a5f10
          description: The ID of the blob server session returned by /session-service/1.0/create-session
        - in: query
          name: blob-id
          schema:
            type: string
            format: uuid
          example: 4D7C7BB1-7AEF-4CD2-9146-0286561D6F85
          description: The final (Portal Server side) ID of the blob to download
        - in: query
          name: filename
          schema:
            type: string
          example: file.png
          description: The desired filename of the data to be downloaded.
      responses:
        200:
          description: File data downloading.
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
                example: <binary data>
        430:
          description: File can not be downloaded.
          content:
            application/vnd.graphisoft.teamwork.generic-service-1.0.detailed-error-1.0+json:
              schema:
                $ref: '#/components/schemas/BlobServerDetailedError'

components:
  schemas:

  # ENTITY TYPES

    Resource:
      type: object
      properties:
        id:
          type: string
          format: uuid
          example: 33E36B98-2758-4C17-83E5-69E93B8B87CB
          description: The ID of the requested resource
        type:
          type: string
          example: blob
          description: The type of the requested resource
        name:
          type: string
          example: file.png
          pattern: ^[^<>:;,?\"*|\/\\\\]+$
          description: The name of the resource excluding path. Similar to filename.
        $path:
          type: string
          example: 'Project Root/folder/file.png'
          description: The full path of the resource. The root folder is called "Project Root" and may be translated.
        $loweredPath:
          type: string
          example: 'project root/folder/file.png'
          description: Same as $path, but lowercase.
        $ancestors:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                description: The ancestor's id
              name:
                type: string
                description: The ancestor's name
            example: [
              {
                id: projectRoot,
                name: Project Root
              },
              {
                id: 8631e8b4-911d-43c0-ae15-cbd3d49018eb,
                name: folder
              }
            ]
            description: |
              The array of ancestors of the resource entitiy in the resource tree. The 0th item is the root of the tree,
              while subsequent items represent one level of depth in the resource tree. The last item is the direct ancestor
              of the requested resource.
        $parentId:
          type: string
          format: uuid
          example: 8631e8b4-911d-43c0-ae15-cbd3d49018eb
          description: The ID of the requested resource's immediate ancestor.
        $parentName:
          type: string
          example: folder
          description: The name of the requested resource's immediate ancestor.
        $modelServerName:
          type: string
          example: model1
          description: The name of the host server
        $modelServerPath:
          type: string
          example: Server Root/model1
          description: |
            The path of the host server. Similar to $path. The root folder is called "Server Root", which may be translated.
            Servers may be nested in folders in a tree the same way as regular resources.
        modelServerId:
          type: string
          example: d290f1ee-6c54-4b01-90e6-d701748f0853
          format: uuid
          description: The ID of the host server.
        $modifiedDate:
          type: integer
          example: 1585303324545
          description: The timestamp of the last modification made to the resource
        $size:
          type: integer
          example: 484173
          description: The size of the requested resource in bytes.

  # RESPONSES & CO.

    CreateSessionRequest:
      type: object
      properties:
        client-id:
          description: The ID of the client requesting the session
          type: string
          example: someclient
        username:
          type: string
          example: some-user
          description: "Username of the user initiating the request. NOTE: this is case sensitive."
        password:
          description: |
            **IMPORTANT** The password is in cleartext, so it is **IMPERATIVE** that the API gets published via https
          type: string
          example: P4$$w0rD

    CreateSessionResponse:
      type: object
      properties:
        session-id:
          description: The ID of the created session. This ID will be required in every subsequent query.
          type: string
          format: uuid
          example: d290f1ee-6c54-4b01-90e6-d701748f0851
        user-id:
          description: The ID of the user who created the session
          type: string
          format: uuid
          example: d290f1ee-6c54-4b01-90e6-d701748f0852
        expire-timeout:
          description: The amout of time in milliseconds until the session expires upon inactivity
          type: integer
          example: 1234567

    CriterionObject:
      type: object
      description: |
        Describes the criteria of a database query, similar to mongodb criterions or SQL WHERE clauses.
        See the example for details.

        Operators: $and, $or, $eq, $ne, $like, $gt, $gte, $lt, $lte, $not
      example:
        {
          $and: [
            { $eq: { name: 'file.png' } },
            { $eq: { parentId: '8631e8b4-911d-43c0-ae15-cbd3d49018eb' } }
          ]
        }

    GetTicketRequest:
      type: object
      properties:
        user-id:
          description: The ID of the user who requested the session. Returned by /management/client/create-session
          type: string
          format: uuid
          example: d290f1ee-6c54-4b01-90e6-d701748f0852
        format:
          description: |
            Controls the format and the response type of the ticket generation. Format `base64` returns the ticket data
            in a string encoded in base64, while `lengthPrefixedBuffer` returns a binary buffer.
            When unspecified, it will default to `lengthPrefixedBuffer`. The preferred format is `base64`.
          type: string
          pattern: base64|lengthPrefixedBuffer
          example: base64
        type:
          description: The type of the ticket to be requested. Only `freeTicket` is supported.
          type: string
          example: freeTicket
        resources:
          description: |
            A one element array containing the ID of the resource that the ticket is requested for. For file management,
            the array should contain the ID of the desired blob server. This ID may be obtained by calling
            `/management/client/get-inherited-default-blob-server-id`, where the `resource-group-id` parameter is
            the ID of the future target upload's parent directory.
          type: array
          items:
            type: string
            format: uuid
          maxLength: 1
          minLength: 1
          example: ['d290f1ee-6c54-4b01-90e6-d701748f0853']

    GetTicketResponseBase64:
      type: string
      format: base64
      example: VGlja2V0IGRhdGEgcmV0dXJuZWQgZnJvbSAvbWFuYWdlbWVudC9jbGllbnQvdGlja2V0LWdlbmVyYXRvci9nZXQtdGlja2V0Cg==
      description: The ticket data encoded in base64. For future blob server queries, provide this ticket as-is.

    GetTicketResponseLengthPrefixedBuffer:
      type: string
      format: binary
      example: <binary data>
      description: Binary ticket data.

    BlobServerAuthenticationRequest:
      type: object
      properties:
        data-content-type:
          type: string
          example: application/vnd.graphisoft.teamwork.session-service-1.0.authentication-request-1.0+json
        data:
          type: object
          properties:
            username:
              type: string
              example: some-user
              description: The username of the user requesting the new session
            ticket:
              type: string
              format: base64
              example: VGlja2V0IGRhdGEgcmV0dXJuZWQgZnJvbSAvbWFuYWdlbWVudC9jbGllbnQvdGlja2V0LWdlbmVyYXRvci9nZXQtdGlja2V0Cg==
              description: The base64 ticket data returned by `/management/client/ticket-generator/get-ticket`

    BlobServerSessionResponse:
      type: object
      properties:
        id:
          type: string
          example: 5cf6ee792cdf05e1ba2b6325c41a5f10
          format: guid
          description: The ID of the session created by the Blob Server
        last-access-time:
          type: integer
          example: 123456
          description: Timestamp of the last access of the Blob Server APIs by this session in seconds.
        expiration-time:
          type: integer
          example: 123456
          description: Timestamp of the expiration time of this session in seconds
        creation-time:
          type: integer
          example: 123456
          description: Timestamp of when this session expires in seconds

    BlobServerBatchUploadSessionResponse:
      type: object
      properties:
        id:
          type: string
          example: 832DBA54-7E0B-463C-B0EF-DB65DAB25745
          format: uuid
          description: The ID of the batch upload session created by the Blob Server
        namespace-name:
          type: string
          example: 832DBA54-7E0B-463C-B0EF-DB65DAB25745
          format: uuid
          description: The ID of the namespace associated with the batch upload session created by the Blob Server
        description:
          type: string
          example: description
          description: The description of the batch being uploaded, same as the description sent in the request.
        last-access-time:
          type: integer
          example: 1585234790629
          description: Timestamp of the last access of the Blob Server APIs by this session in milliseconds.
        expiration-time:
          type: integer
          example: 1585249190629
          description: Timestamp of the expiration time of this session in milliseconds.
        creation-time:
          type: integer
          example: 1585234790629
          description: Timestamp of when this session was created in milliseconds.
        events:
          type: array
          items:
            type: string
          example: []
          description: Names of the events that occured during the session.

    BlobServerUploadSessionResponse:
      type: object
      properties:
        id:
          type: string
          example: 6894B3DD-74FE-48AE-BD5E-266861659B13
          format: uuid
          description: The ID of the upload session created by the Blob Server
        target-namespace-name:
          type: string
          example: 832DBA54-7E0B-463C-B0EF-DB65DAB25745
          format: uuid
          description: The namespace associated with the batch upload session that this upload session belongs to
        target-blob-name:
          type: string
          example: /folder/file.png
          description: The filename of the file being uploaded, including the path, as supplied as a query parameter to /blob-store-service/1.0/begin-upload
        target-blob-id:
          type: string
          example: ""
          description: The ID of the blob being created by this upload-session, when target-blob-id is given.
        last-access-time:
          type: integer
          example: 1585234790629
          description: Timestamp of the last access time of this session in milliseconds.
        expiration-time:
          type: integer
          example: 1585249190629
          description: Timestamp of the expiration time of this session in milliseconds.
        creation-time:
          type: integer
          example: 1585234790629
          description: Timestamp of when this session was created in milliseconds.
        uploaded-parts:
          type: array
          items:
            type: object
            properties:
              offset:
                type: integer
                description: The offset of the chunk that was already uploaded from the beginning of the blob in bytes
                example: 0
              length:
                type: integer
                description: The size of the chunk that was already uploaded in bytes
                example: 484173
          description: The parts of this file that were already uploaded. Empty initially.

    BlobServerBlobMetadataResponse:
      type: object
      properties:
        standard-metadata:
          type: object
          properties:
            namespace-name:
              type: string
              example: 832DBA54-7E0B-463C-B0EF-DB65DAB25745
              format: uuid
              description: The namespace associated with the batch upload session that the committed upload session belongs to
            blob-name:
              type: string
              example: /folder/file.png
              description: The full path of the file that was uploaded
            blob-id:
              type: string
              example: 33E36B98-2758-4C17-83E5-69E93B8B87CB
              format: uuid
              description: |
                The ID of the uploaded blob.
                The ID is a temporary, non-final identifier until `/blob-store-service/1.0/commit-batch-upload` is called.
                The ID retured during `/blob-store-service/1.0/commit-upload` **will** change during
                `/blob-store-service/1.0/commit-upload`!
            metadata-revision:
              type: string
              format: number
              example: "1"
              description: The metadata revision number of the file that was uploaded. Edits to the file metadata increase this value.
            content-revision:
              type: string
              format: number
              example: "1"
              description: The content revision number of the file that was uploaded. Edits to the contents of the file increase this value.
            access:
              type: string
              example: opened
              description: Describes access status
            last-modified-by-user-name:
              type: string
              example: some-user
              description: The username of the user who initiated the last edit to this file
            last-modified-by-user-id:
              type: string
              format: uuid
              example: d290f1ee-6c54-4b01-90e6-d701748f0852
              description: The ID of the user who initiated the last edit to this file
            last-modified:
              type: string
              format: number
              example: "1585234790835"
              description: The timestamp of the latest change made to this file in milliseconds
            created-by-user-name:
              type: string
              example: some-user
              description: The username of the user who initially uploaded this file
            created-by-user-id:
              type: string
              format: uuid
              example: d290f1ee-6c54-4b01-90e6-d701748f0852
              description: The ID of the user who initially uploaded this file
            created:
              type: string
              format: number
              example: "1585234790835"
              description: The timestamp of the initial upload of this file in milliseconds
            content-disposition:
              type: string
              example: attachment; filename="/folder/file.png"
              description: Content disposition of the file
            content-language:
              type: string
              example: ""
              description: Language of file contents
            content-type:
              type: string
              example: application/octet-stream
              description: Content type of this file
            content-hash-algorithm:
              type: string
              example: SHA256
              description: Name of the algorithm used for hashing the file content
            content-hash:
              type: string
              example: E_UXOOjE-SDi-g_Tq6F7dQAd1dp-C5aLTIy1ThHFvFQ
              description: The hash generated by the hash function described in content-hash-algorithm
            cache-control:
              type: string
              example: no-cache
              description: Describes cache
            e-tag:
              type: string
              example: E_UXOOjE-SDi-g_Tq6F7dQAd1dp-C5aLTIy1ThHFvFQ
              description: The e-tag associated with the file.
            size:
              type: string
              format: number
              example: "484173"
        user-metadata:
          type: object
          description: Reserved for future use.

    GetBlobChangesForSyncResponseCreatedOrUpdatedObject:
      type: object
      properties:
        id:
          type: string
          format: uuid
        path:
          type: string
          example: Project Root/folder1/blob1.jpg
        timestamp:
          type: number
          example: 8124389429384.234
        revision:
          type: integer
          example: 1

    Job:
      type: object
      properties:
        id:
          type: string
          format: uuid
        authorId:
          type: string
          format: uuid
          nullable: true
          description: Identifier of the user who started the job.
        isService:
          type: boolean
          description: Started by system (true), or by a user (false).
        startedOn:
          type: number
          description: Start time (JavaScript timestamp).
        progressedOn:
          type: number
          description: Last progress time (JavaScript timestamp).
        status:
          type: string
          enum: ['starting', 'running', 'failed', 'completed', 'aborted', 'aborting', 'undoing', 'abort failed']
          description: >
            Job status:
              * `starting` - Job is about to get started.
              * `running` - Job is running.
              * `failed` - Job failed.
              * `completed` - Job completed.
              * `aborted` - Job aborted.
              * `aborting` - Job has been aborted, and processing its abort state. Status will go to *aborted* or *abort failed* from there eventually.
              * `undoing` - Job has been failed, and undoing its partially completed operation. Status will go to *failed* from there eventually.
              * `abort failed` - Job aborted, but there was an error while doing its abort operation.
        jobType:
          type: string
          example: destroyResources
          description: Type of the job.
        progress:
          type: object
          properties:
            min:
              type: number
              example: 0
            max:
              type: number
              example: 100
            current:
              type: number
              example: 50
              description: Job actual progress between *min* and *max*.
            phase:
              type: string
              example: removingElements
              description: Phase identifier of multi-phase jobs. Empty string if the job is single phased.
        result:
          type: string
          nullable: true
          description: |
            Job dependent result value if *status* is *completed*.

            Error message if *status* is *failed* or *abort failed*.
        resultCode:
          type: string
          nullable: true
          description: |
            Job dependent result code if *status* is *completed*, usually zero.

            Error code if *status* is *failed* or *abort failed*.
        abortable:
          type: boolean
          description: |
            If true, job supports abort operation.


    # FS ERRORS

    BlobServerDetailedError:
      type: object
      properties:
        data-content-type:
          type: string
          example: application/vnd.graphisoft.teamwork.generic-service-1.0.detailed-error-1.0+json
        data:
          type: object
          properties:
            error-message:
              type: string
              example: "Failed to execute request: 'session-service-create-session'. Error: 'Authentication failed: access control ticket is expired.'."
              description: The error message generated by the Blob Server
            error-code:
              type: integer
              example: 4
              pattern: '[1-5]|1[1-9]|2[0-3]'
              description: |
                Error code-name pairs:
                  - `1` `GenericError`
                  - `2` `AuthenticationRequired`
                  - `3` `AuthenticationFailed`
                  - `4` `AccessControlTicketExpired`
                  - `5` `AccessDenied`
                  - `11` `SessionNotFound`
                  - `12` `BatchUploadCommitFailed`
                  - `13` `InvalidBlobContentPart`
                  - `14` `UploadSessionNotFound`
                  - `15` `IncompleteUpload`
                  - `16` `BlobAttachmentNotFound`
                  - `17` `BlobNamespaceNotFound`
                  - `18` `BlobRevisionNotFound`
                  - `19` `BlobChunkNotFound`
                  - `20` `BlobAlreadyExists`
                  - `21` `BlobNotFound`
                  - `22` `BlobAccessDenied`
                  - `23` `BlobPermissionDenied`
            details:
              type: object
              properties:
                message:
                  type: string
                  example: "Authentication failed: access control ticket is expired."
                  description: The error message generated by the Blob Server
                reason:
                  type: string
                  example: AccessControlTicketExpired
                  description: The internal name of the error thrown. See the description of error-code for details.

    # PS ERRORS

    PortalServerError:
      type: object
      properties:
        error-code:
          type: integer
          example: 6
          description: |
            The code of the error being thrown. Current error code-name pairs:
              - `1` `GenericError`
              - `2` `AuthenticationRequiredError`
              - `3` `AccessDeniedError`
              - `4` `EntityCyclicDependencyError`
              - `5` `EntityExistsError`
              - `6` `EntityNotFoundError`
              - `7` `EntityValidationError`
              - `8` `OptimisticLockError`
              - `9` `RevisionObsoletedError`
              - `10` `LdapConnectionError`
              - `11` `LdapInvalidCredentialsError`
              - `12` `FileConnectionBaseDnError`
              - `13` `ModelServerSideError`
              - `14` `ReferenceError`
              - `15` `ProhibitDeleteError`
              - `16` `LicenseManagerError`
              - `17` `ResultLimitExceededError`
              - `18` `ModelServerNotCompatibleError`
              - `19` `NotEnoughFreeSpaceError`
              - `20` `ChangeHostError`
              - `21` `GSIDConnectionError`
              - `22` `GSIDInvalidCredentialsError`
              - `23` `TagAlreadyAssignedError`
              - `24` `KeyExistsError`
              - `25` `NotAllowedError`
              - `26` `NotYetAvailableError`
              - `27` `InsufficientLicenseError`
        error-message:
          type: string
          example: 'EntityNotFoundError: No item found by "projectRootz"'
          description: Details about why the error has occured