openapi: 3.0.0
info:
  title: OpenCDE Documents API
  description: OpenCDE Documents API Specification
  version: '1.0'
paths:
  /server-provided-path-document-metadata:
    get:
      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:
      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'
  /server-provided-path-document-version:
    get:
      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. Clients that need to monitor for new document versions may periodically poll this endpoint, but should honor the 'ETag' header. This endpoint should not be called more frequently than once every ten seconds per each distinct document url.
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentVersion'
  /server-provided-path-selected-documents-url:
    get:
      tags:
        - Download
      description: This endpoint returns the document selection. The client retrieves its url via the callback url from the server after the selection has finished. The url of this endpoint is retrieved from the callback sent to the client in 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'
  /server-provided-path-upload-documents-url:
    post:
      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. The url of this endpoint is retrieved from the callback sent to the client in 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 generate multiple upload parts, if required.'
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UploadFileDetails'
        required: true
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentsToUpload'
        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:
    put:
      tags:
        - Upload
      description: This endpoint allows the client to upload the file content. The clients obtains this through the document upload information response.
      requestBody:
        content:
          application/octet-stream:
            schema:
              type: string
              format: binary
      responses:
        200:
          description: ''
  /server-provided-path-document-upload-completion:
    post:
      tags:
        - Upload
      description: This endpoint must be called by the client when the file content upload has completed successfully. The clients obtains this through the document upload information response.
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentVersion'
  /server-provided-path-document-upload-cancellation:
    post:
      tags:
        - Upload
      description: This endpoint must be called by the client when the file content upload has been cancelled. The clients obtains this through the document upload information response.
      responses:
        204:
          description: ''
  /select-documents:
    post:
      tags:
        - Download
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SelectDocuments'
        required: true
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentDiscoverySessionInitialization'
  /upload-documents:
    post:
      tags:
        - Upload
      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. After a document upload has been prepared, the CDE will issue a redirect to the provided callback url with a query parameter called `upload_documents_url`. By calling this url, the client can continue with the upload flow, it corresponds to the server specific location of `/server-provided-path-upload-documents-url`.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UploadDocuments'
        required: true
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentUploadSessionInitialization'
  /document-versions:
    post:
      tags:
        - Query
      description: This endpoint must be called when querying the latest versions for multiple documents. It's an aggregate endpoint that should make periodic polling of a collection of documents easier. Servers must also support the ETag header for this endpoint, so clients may specifiy to receive a response object in case of changes on the server since the last query. It will return a list of DocumentVersion objects, where each DocumentVersion represents the latest version for each given document on the server.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DocumentQuery'
        required: true
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentQueryResult'
components:
  schemas:
    DocumentMetadata:
      type: object
      additionalProperties: false
      required:
      - metadata
      properties:
        metadata:
          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 default authorization of the CDE in the file upload 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: 'Please note, that if a server supplies custom data here to be used in multipart requests, it is very likely that the server will also have to 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:
      type: object
      additionalProperties: false
      required:
      - name
      - value
      - data_type
      properties:
        name:
          type: string
          minLength: 1
        value:
          type: array
          items: 
            type: string
            minLength: 1
        data_type:
          type: string
          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
        documents:
          type: array
          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
        file_description:
          $ref: '#/components/schemas/FileDescription'
        document_id:
          type: string
          minLength: 1
    DocumentVersionLinks:
      type: object
      additionalProperties: false
      required:
      - document_version
      - document_version_metadata
      - document_version_download
      - document_versions
      description: 'The document_details property represents an 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
      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
        expires_in:
          type: integer
          format: int32
    SelectDocuments:
      type: object
      additionalProperties: false
      required:
      - callback
      properties:
        callback:
          $ref: '#/components/schemas/CallbackLink'
        server_context:
          type: string
          nullable: true
        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
        session_file_id:
          type: string
          minLength: 1
    UploadDocuments:
      type: object
      additionalProperties: false
      required:
      - callback
      - files
      properties:
        callback:
          $ref: '#/components/schemas/CallbackLink'
        server_context:
          type: string
          nullable: true
        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
        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
    DocumentUploadSessionInitialization:
      type: object
      additionalProperties: false
      required:
        - upload_ui_url
        - expires_in
        - max_size_in_bytes
      properties:
        upload_ui_url:
          type: string
          minLength: 1
        expires_in:
          type: integer
          format: int32
        max_size_in_bytes:
          type: integer
          format: int64
    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
        expires_in:
          type: integer
          format: int32
    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'