swagger.yaml

openapi: 3.0.0
info:
  title: OpenCDE Documents API
  description: OpenCDE Documents API Specification
  version: '1.0'
paths:
  /select-documents:
    post:
      summary: 'Initiate document selection and download flow' 
      operationId: /select-documents
      tags:
        - Download
      description: > 
        The client will call this endpoint to initiate the flow of selecting and downloading documents. 
      requestBody:
        description: 'The body of this request contains a callback URL to the client, which is used later in the flow to communicate from the CDE server back to the client via query parameters.'      
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SelectDocuments'
        required: true
      responses:
        200:
          description: 'The CDE returns a URL for the client to open in a local browser. The user will then be presented with the CDE UI to select and download documents'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentDiscoverySessionInitialization'
          links:
            /server-provided-path-selected-documents-url:
              operationId: /server-provided-path-selected-documents-url
              description: >
                * Once the user has completed selecting documents in the CDE UI, the CDE will append `?selected_documents_url=/server-provided-path-selected-documents-url` to the client's callback (see request) and provide it to the client via a browser redirect.
                
                * IF the user has cancelled the download the CDE server will append `?user_cancelled_selection=true` to the client's callback (see request) and provide it to the client via a browser redirect.

  /server-provided-path-selected-documents-url:
    get:
      summary: 'Retrieve the user''s selection from the CDE' 
      operationId: /server-provided-path-selected-documents-url
      tags:
        - Download
      description: This endpoint returns the document selection. The client retrieves its URL via the callback URL from the CDE after the selection has finished from a query parameter named `selected_documents_url`. In case when the user cancels the selection on the CDE UI, this callback will still be called, but the `selected_documents_url` query parameter will not be present, instead the server will provide a query parameter called `user_cancelled_selection=true`.
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SelectedDocuments'
          links:
            /server-provided-path-document-download:
              operationId: /server-provided-path-document-download
              description: >
                Use the `document_version_download` operation to download the file contents
            /server-provided-path-document-metadata:
              operationId: /server-provided-path-document-metadata
              description: >
                Use the `document_version_metadata` URL operation to retrieve document metadata                 
                
  /upload-documents:
    post:
      summary: 'Initiate the upload flow' 
      operationId: /upload-documents
      tags:
        - Upload
      description: 'The client will call this endpoint to initiate the flow of uploading documents to the CDE.' 
      requestBody:
        description: 'The body of this request contains a list of files to upload and a callback URL to the client, which is used later in the flow to communicate from the CDE server back to the client via query parameters.'
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UploadDocuments'
        required: true
      responses:
        200:
          description: 'The CDE returns a URL for the client to open in a local browser. The user will then be presented with the CDE UI to enter document metadata'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentUploadSessionInitialization'
          links:
            /server-provided-path-upload-documents-url:
              operationId: /server-provided-path-upload-documents-url
              description: >
                * Once the user has completed entering document metadata in the CDE UI, the CDE will append `?upload_documents_url=/server-provided-path-upload-documents-url` to the client's callback (see request) and provide it to the client via a browser redirect 
                
                * If the user has cancelled the download the CDE server will append `?user_cancelled_selection=true` to the client's callback (see request) and provide it to the client via a browser redirect.


  /server-provided-path-document-download:
    get:
      summary: 'Download the document'
      operationId: /server-provided-path-document-download
      tags:
        - Download
      description: Use this endpoint to download the document. Its URL is retrieved from the links object in the initial document selection response, with the `document_version_download` property.
      responses:
        200:
          description: 'The file content'
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
  /server-provided-path-document-metadata:
    get:
      summary: 'Get document metadata for a single document'
      operationId: /server-provided-path-document-metadata
      tags:
        - Download
      description: This endpoint returns the metadata for a single document. Its URL is retrieved from the links object in the initial document selection response, with the `document_version_metadata` property.
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentMetadata'
  /server-provided-path-document-versions:
    get:
      summary: 'Get the versions of a single document'
      operationId: /server-provided-path-document-versions
      tags:
        - Download
      description: This endpoint returns the versions for a single document. Its URL is retrieved from the links object in the initial document selection response, with the `document_versions` property.
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentVersions'
          links:
            /document-versions:
              operationId: /document-versions
              parameters: 
                document_id: '$response.body#..document_id'
              description: >
                Use the `document_id` to query for updates for this document 
          
  /server-provided-path-document-version:
    get:
      summary: "Get the information for a single document version"
      operationId: /server-provided-path-document-version
      tags:
        - Download
      description: This endpoint returns the document data for a single document. Its URL is retrieved from the links object in the initial document selection response, with the `document_version` property.
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentVersion'
          links:
            /document-versions:
              operationId: /document-versions
              parameters: 
                document_id: '$response.body#..document_id'
              description: >
                Use the `document_id` to query for updates for this document 
          
  /server-provided-path-upload-documents-url:
    post:
      summary: 'Retrieve upload instructions after the user has entered document metadata on the CDE' 
      operationId: /server-provided-path-upload-documents-url
      tags:
        - Upload
      description: This endpoint returns the document upload information. The client retrieves this URL via the callback URL from the server after the user's completion of the upload metadata entry from a query parameter named `upload_documents_url`. In case when the user cancels the upload on the CDE UI, this callback will still be called, but the `upload_documents_url` query parameter will not be present, instead the server will provide a query parameter called `user_cancelled_upload=true`.
      requestBody:
        description: 'The client sends the list of files to be uploaded with this request. The file sizes are then used by the server to break the file to multiple upload parts, as required.'
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UploadFileDetails'
        required: true
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentsToUpload'
          links:
            /server-provided-path-document-upload-file-part:
              operationId: /server-provided-path-document-upload-part
              description: >
                This operation should be called for each part specified in this reponse          
            /server-provided-path-document-upload-completion:
              operationId: /server-provided-path-document-upload-completion
              description: >
                This operation should be called when all the parts have been successfully uploaded         
            /server-provided-path-document-upload-cancellation:
              operationId: /server-provided-path-document-upload-cancellation
              description: >
                This operation should be called to cancel the upload        
                
        400:
          description: 'This error may be returned if the file size exceeds the maximum length supported by the server.'
  /server-provided-path-document-upload-file-part:
    put:
      summary: 'Upload a single file part' 
      description: > 
        This endpoint allows the client to upload the content of a single file part. 
        
        * The `/server-provided-path-upload-documents-url` operation specifies the list of part upload requests for each file
        
        * For each part, the URL, method (put or post), headers and request body are specified
        
        * The client must upload all parts before proceeding to complete the upload
        
        * Parts can be uploaded concurrently and in any order
        
      operationId: /server-provided-path-document-upload-file-put
      tags:
      - Upload
      requestBody:
        content:
          application/octet-stream:
            schema:
              type: string
              format: binary
      responses:
        200:
          description: ''
          links:
            /server-provided-path-document-upload-completion:
              operationId: /server-provided-path-document-upload-completion
              description: >
                This operation should be called when all the parts have been successfully uploaded         
            /server-provided-path-document-upload-cancellation:
              operationId: /server-provided-path-document-upload-cancellation
              description: >
                This operation should be called to cancel the upload        
               
    post:
      summary: 'Upload a single file part' 
      description: > 
        This endpoint allows the client to upload the content of a single file part.
        
        * The `/server-provided-path-upload-documents-url` operation specifies the list of part upload requests for each file
        
        * For each part, the URL, method (put or post), headers and request body are specified
        
        * The client must upload all parts before proceeding to complete the upload
        
        * Parts can be uploaded concurrently and in any order
        
      operationId: /server-provided-path-document-upload-file-post
      tags:
        - Upload
      requestBody:
        content:
          application/octet-stream:
            schema:
              type: string
              format: binary
      responses:
        200:
          description: ''    
          links:
            /server-provided-path-document-upload-completion:
              operationId: /server-provided-path-document-upload-completion
              description: >
                This operation should be called when all the parts have been successfully uploaded         
            /server-provided-path-document-upload-cancellation:
              operationId: /server-provided-path-document-upload-cancellation
              description: >
                This operation should be called to cancel the upload        
               
          
  /server-provided-path-document-upload-completion:
    post:
      summary: 'Complete a file upload after all the parts have been successfully uploaded' 
      operationId: /server-provided-path-document-upload-completion
      tags:
        - Upload
      description: > 
        The `/server-provided-path-upload-documents-url` operation specifies the upload completion URL for each file. The upload completion endpoint must be called by the client when the file content upload has completed successfully. 
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentVersion'
  /server-provided-path-document-upload-cancellation:
    post:
      summary: 'Cancel the upload of a single file' 
      operationId: /server-provided-path-document-upload-cancellation
      tags:
        - Upload
      description: > 
        The `/server-provided-path-upload-documents-url` operation specifies the upload cancellation URL for each file. This endpoint must be called by the client when the file content upload has been cancelled. 
      responses:
        204:
          description: ''
  /document-versions:
    post:
      summary: 'Query for the latest versions of multiple documents' 
      operationId: /document-versions
      tags:
        - Query
      description: This endpoint can be called when querying for the latest versions for multiple documents. It's an aggregate endpoint that should make periodic polling of a collection of documents easier. 
      parameters:
        - in: header
          name: If-None-Match
          description: 'Clients may provide a previosuly received etag value to avoid receiving a response object if there were no changes since the last query'
          schema:
            type: string
            format: etag_value
          required: false
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DocumentQuery'
        required: true
      responses:
        200:
          description: 'A list of DocumentVersion objects, where each DocumentVersion represents the latest version for each given document on the server.'
          headers:
            ETag:
              schema:
                type: string
                format: etag_value
              description: A unique identifier of the response that allows CDEs to save bandwidth and the clients to implement caching and avoid computation when the document versions haven't changed since the last query
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentQueryResult'
          links:
            /server-provided-path-document-versions:
              operationId: /server-provided-path-document-versions
              description: >
                This operations allows listing all the versions of a document that has been flagged to have a new version in the response. 
components:
  schemas:
    DocumentMetadata:
      type: object
      additionalProperties: false
      required:
      - metadata
      properties:
        metadata:
          description: 'An array of metadata entries'
          type: array
          items:
            $ref: '#/components/schemas/DocumentMetadataEntry'
    LinkData:
      type: object
      additionalProperties: false
      required:
      - url
      properties:
        url:
          type: string
          minLength: 1
    UploadFilePartInstruction:
      description: 'This model describes how a single part of a multipart file upload should be processed by the client. The upload links may only be valid for a specific time period, after which the links expire. Server vendors should make sure to have a reasonably long expiration date for clients to upload large files'
      allOf:
        - $ref: '#/components/schemas/LinkData'
        - type: object
          required:
            - http_method
            - content_range_start
            - content_range_end
          properties:
            http_method:
              type: string
              enum: [POST, PUT]
            additional_headers:
              $ref: '#/components/schemas/Headers'
            include_authorization:
              description: 'Whether or not to include the authorization request header in the file upload request. Including the authorization header with some cloud storage providers might fail the request'
              type: boolean
              default: false
            multipart_form_data:
              $ref: '#/components/schemas/MultipartFormData'
            content_range_start:
              description: 'The inclusive, zero index based start for this part'
              type: integer
              format: int64
            content_range_end:
              description: 'The inclusive, zero index based end for this part'
              type: integer
              format: int64
    MultipartFormData:
      type: object
      additionalProperties: false
      description: 'Multipart Form Data descriptor. If the CDE provided custom data here to be used in multipart requests then it is very likely that the CDE will also set a custom Content-Type header with the multipart/form-data type and a server-provided boundary'
      required:
        - prefix
        - suffix
      properties:
        prefix:
          description: 'This is a server provided value. Its value must be prefixed to the binary content body when uploading this part'
          type: string
          format: byte
        suffix:
          description: 'This is a server provided value. Its value must be suffixed to the binary content body when uploading this part. Typically, this is the end boundary for a multipart/form-data request'
          type: string
          format: byte
    DocumentMetadataEntry:
      description: 'A single document metadata property - a key-value pair'
      type: object
      additionalProperties: false
      required:
      - name
      - value
      - data_type
      properties:
        name:
          type: string
          minLength: 1
          description: 'The name of the metadata property'
        value:
          type: array
          description: 'The value of the metadata property, can be a list'
          items: 
            type: string
            minLength: 1
        data_type:
          type: string
          description: 'The data type of the items in the value array'
          enum:
          - string
          - boolean
          - date-time
          - date
          - integer32
          - integer64
          - number
          - url
    DocumentVersions:
      type: object
      additionalProperties: false
      required:
      - documents
      properties:
        documents:
          type: array
          items:
            $ref: '#/components/schemas/DocumentVersion'
    SelectedDocuments:
      type: object
      additionalProperties: false
      required:
      - documents
      properties:
        server_context:
          type: string
          nullable: true
          description:  'A CDE controlled identifier recording the user''s context on the CDE. For example which project and folder the user was on. If the client provides the `server_context` in subsequent calls then the CDE will attemp to load the UI at the same place.'
        documents:
          type: array
          description: 'An array containing all the documents selected by the user'
          items:
            $ref: '#/components/schemas/DocumentVersion'
    DocumentVersion:
      type: object
      additionalProperties: false
      required:
      - links
      - version_number
      - version_index
      - creation_date
      - title
      - file_description
      - document_id
      properties:
        links:
          $ref: '#/components/schemas/DocumentVersionLinks'
        version_number:
          description: 'A human readable version number. This is not expected to be in any specific format across CDEs and may hold any value'
          type: string
          minLength: 1
        version_index:
          description: 'A machine readable sequence number of the version of the document. The sequence must be ordered, so that newer versions have higher values than previous ones. Each version index must be unique for that document, but there may be gaps in the sequence'
          type: integer
          format: int32
        creation_date:
          description: 'The creation date of the document revision'
          type: string
          format: date-time
          minLength: 1
        title:
          type: string
          minLength: 1
          description: 'A human readable code or identifier'
        file_description:
          $ref: '#/components/schemas/FileDescription'
        document_id:
          type: string
          minLength: 1
          description: "A machine readable identifier that can be used to uniquely identify this version it future calls - see `Query` section"
    DocumentVersionLinks:
      type: object
      additionalProperties: false
      required:
      - document_version
      - document_version_metadata
      - document_version_download
      - document_versions
      description: > 
         * __document_version__ is a self-URL that can be used for future retrieval of the document version information
         
         * __document_version_metadata__ is a URL for retrieving the metadata associated with this document version
         
         * __document_version_download__ is a URL for downloading the file backing this document version
         
         * __document_versions__ is a URL for retrieving all the versions of the document
         
         * __document_details__ is a URL that should be opened in the system browser. It leads to a page on the CDE where users can view or edit document details
         
      properties:
        document_version:
          $ref: '#/components/schemas/LinkData'
        document_version_metadata:
          $ref: '#/components/schemas/LinkData'
        document_version_download:
          $ref: '#/components/schemas/LinkData'
        document_versions:
          $ref: '#/components/schemas/LinkData'
        document_details:
          $ref: '#/components/schemas/LinkData'
    FileDescription:
      type: object
      additionalProperties: false
      description: 'Basic file information'
      required:
      - name
      - size_in_bytes
      properties:
        name:
          type: string
          minLength: 1
        size_in_bytes:
          type: integer
          format: int64
    DocumentDiscoverySessionInitialization:
      type: object
      additionalProperties: false
      required:
      - select_documents_url
      - expires_in
      properties:
        select_documents_url:
          type: string
          minLength: 1
          description: 'A CDE UI URL for the client to open in a local browser. The user would search and select documents directly in the CDE'
        expires_in:
          type: integer
          format: int32
          description: '`select_documents_url` expiry in seconds'
    SelectDocuments:
      type: object
      additionalProperties: false
      required:
      - callback
      properties:
        callback:
          $ref: '#/components/schemas/CallbackLink'
        server_context:
          type: string
          nullable: true
          description:  'A CDE controlled identifier recording the user''s context on the CDE. For example which project and folder the user was on. If the client provides the `server_context` in subsequent calls then the CDE will attemp to load the UI at the same place.'
        supported_file_extensions:
          description: 'The client may optionally provide an array of accepted file extensions that should be opened during this flow. The CDE server UI should make an attempt to only show files matching these extensions to the user for the download selection or help the user in selecting the desired files. However, the server does not have to guarantee that only files matching the extensions will be selected. The extensions here must contain the dot separator.'
          example: [".ifc", ".ifczip"]
          type: array
          items:
            type: string
    UploadFileDetails:
      type: object
      description: 'This object holds information about files to be uploaded. Each file in the array needs a file size so that the server can calculate the needed parts for a multipart upload. The session_file_id is used to identify the file.'
      additionalProperties: false
      required:
      - files
      properties:
        files:
          type: array
          items:
            $ref: '#/components/schemas/UploadFileDetail'
    UploadFileDetail:
      type: object
      additionalProperties: false
      required:
      - size_in_bytes
      - session_file_id
      properties:
        size_in_bytes:
          type: integer
          format: int64
          description: 'The uploaded file size'
        session_file_id:
          type: string
          minLength: 1
          description: 'This is a client provided id to differentiate between multiple files that are being uploaded in the same session'
    UploadDocuments:
      type: object
      additionalProperties: false
      required:
      - callback
      - files
      properties:
        callback:
          $ref: '#/components/schemas/CallbackLink'
        server_context:
          type: string
          nullable: true
          description:  'A CDE controlled identifier recording the user''s context on the CDE. For example which project and folder the user was on. If the client provides the `server_context` in subsequent calls then the CDE will attemp to load the UI at the same place.'
        files:
          type: array
          items:
            $ref: '#/components/schemas/FileToUpload'
    FileToUpload:
      type: object
      additionalProperties: false
      required:
        - file_name
        - session_file_id
      properties:
        file_name:
          type: string
          minLength: 1
          description: "The CDE UI will display this value to the User when entering document metadata"
        session_file_id:
          description: 'This is a client provided id to differentiate between multiple files that are being uploaded in the same session'
          type: string
          minLength: 1
        document_id:
          type: string
          minLength: 1
          description: "When present, indicates that this upload is a new version of an existing document"
    DocumentUploadSessionInitialization:
      type: object
      additionalProperties: false
      required:
        - upload_ui_url
        - expires_in
        - max_size_in_bytes
      properties:
        upload_ui_url:
          type: string
          minLength: 1
          description: 'A CDE UI URL for the client to open in a local browser. The user would enter document metadata directly in the CDE'
        expires_in:
          type: integer
          format: int32
          description: '`upload_ui_url` expiry in seconds'
        max_size_in_bytes:
          type: integer
          format: int64
          description: 'The maximum file size supported by the CDE. Attempts to upload a larger file will fail'
    DocumentsToUpload:
      type: object
      additionalProperties: false
      required:
        - documents_to_upload
      properties:
        server_context:
          type: string
          nullable: true
          description: 'A CDE controlled identifier recording the user''s context on the CDE. For example which project and folder the user was on. If the client provides the `server_context` in subsequent calls then the CDE will attemp to load the UI at the same place.'
        documents_to_upload:
          type: array
          items:
            $ref: '#/components/schemas/DocumentToUpload'
    DocumentToUpload:
      description: 'A specification for the request sequence required to upload a document to the CDE'
      type: object
      additionalProperties: false
      required:
        - session_file_id
        - upload_file_parts
        - upload_completion
        - upload_cancellation
      properties:
        session_file_id:
          type: string
          minLength: 1
          description: 'A client-provided identifier that allows matching the specification with the correct file on the user''s machine'
        upload_file_parts:
          type: array
          minLength: 1
          items:
            $ref: '#/components/schemas/UploadFilePartInstruction'
          description: 'An array of request specifications detailing how to split the file to parts and upload each part to the CDE'
        upload_completion:
          $ref: '#/components/schemas/LinkData'
        upload_cancellation:
          $ref: '#/components/schemas/LinkData'
    CallbackLink:
      type: object
      additionalProperties: false
      required:
      - url
      - expires_in
      properties:
        url:
          type: string
          minLength: 1
          description: >
           The server will web-browser-redirect to this URL once the user has completed 
           selecting documents or entering documenet metadata on the CDE
           
        expires_in:
          type: integer
          format: int32
          description: 'The expiry period for the URL, in seconds'
    Headers:
      description: "An array of required HTTP headers"
      type: object
      required:
        - values
      properties:
        values:
          type: array
          items:
            $ref: '#/components/schemas/HeaderValue'
    HeaderValue:
      description: 'HTTP header descriptor'
      type: object
      required:
      - name
      - value
      properties:
        name:
          type: string
          minLength: 1
        value:
          type: string
          minLength: 1
    DocumentQuery:
      type: object
      description: 'An array of document IDs to track'
      required:
        - document_ids
      properties:
        document_ids:
          type: array
          items:
            type: string
    DocumentQueryResult:
      type: object
      description: 'The versions array contains all the latest document version objects.'
      required:
        - versions
      properties:
        versions:
          type: array
          items:
            $ref: '#/components/schemas/DocumentVersion'