openapi: "3.0.3"
info:
  title: "Resource API"
  description: API to trigger preparation of caches. This allows later requests for the same resources to be fulfilled immediately.
  contact:
    name: Threedy GmbH
    url: https://www.threedy.io/
    email: contact@threedy.io
  version: "3.6.0"
servers:
  - url: '{server}'
    variables:
      server:
        default: https://hubdemo.threedy.io  # Demo Server
paths:
  /api/v1/resource/request:
    post:
      deprecated: true
      description: Used to trigger a preparation. The response can be used to query completion status.
      tags:
        - Request
      requestBody:
        content:
          application/json:
            example:
              elements:
                - uri: urn:x-i3d:shape:sphere
            schema:
              $ref: "#/components/schemas/Elements"
      responses:
        '200':
          description: Success. The body contains handles usable for querying status.
          content:
            'application/json':
              example:
                handles:
                  - name: 21691aef7ba3bafb85b596e109627de97ed8e87d
                    clusterID: cluster-installation-0
                    signature: 304402204558f9424c6052560270fbeaee78885da83c3f822252f05cfb3410d9dc6760620220586b22c6443d145ac2a33b1bb35ad4555b17d6980bf335ee9058b38b3f0f54df-1661258177-4
              schema:
                $ref: "#/components/schemas/Handles"
        '500':
          description: An internal error occurred. The message will give details.
          content:
            'application/json':
              example:
                error:
                  code: 500
                  msg: "failed to handle request: ..."
              schema:
                $ref: "#/components/schemas/Error"
        '400':
          description: The incoming request was malformed.
          content:
            'application/json':
              example:
                error:
                  code: 400
                  msg: "failed to decode request body: ..."
              schema:
                $ref: "#/components/schemas/Error"
  /api/resource/v1/request:
    post:
      description: Used to trigger a preparation. The response can be used to query completion status.
      tags:
        - Request
      requestBody:
        content:
          application/json:
            example:
              elements:
                - uri: urn:x-i3d:shape:sphere
            schema:
              $ref: "#/components/schemas/Elements"
      responses:
        '200':
          description: Success. The body contains handles usable for querying status.
          content:
            'application/json':
              example:
                handles:
                  - name: 21691aef7ba3bafb85b596e109627de97ed8e87d
                    clusterID: cluster-installation-0
                    signature: 304402204558f9424c6052560270fbeaee78885da83c3f822252f05cfb3410d9dc6760620220586b22c6443d145ac2a33b1bb35ad4555b17d6980bf335ee9058b38b3f0f54df-1661258177-4
              schema:
                $ref: "#/components/schemas/Handles"
        '500':
          description: An internal error occurred. The message will give details.
          content:
            'application/json':
              example:
                error:
                  code: 500
                  msg: "failed to handle request: ..."
              schema:
                $ref: "#/components/schemas/Error"
        '400':
          description: The incoming request was malformed.
          content:
            'application/json':
              example:
                error:
                  code: 400
                  msg: "failed to decode request body: ..."
              schema:
                $ref: "#/components/schemas/Error"

  /api/v1/resource/status:
    post:
      deprecated: true
      description: Used to query preparation status. Requires handles from a previous request.
      tags:
        - Query
      requestBody:
        content:
          application/json:
            example:
              handles:
                - name: 21691aef7ba3bafb85b596e109627de97ed8e87d
                  clusterID: cluster-installation-0
                  signature: 304402204558f9424c6052560270fbeaee78885da83c3f822252f05cfb3410d9dc6760620220586b22c6443d145ac2a33b1bb35ad4555b17d6980bf335ee9058b38b3f0f54df-1661258177-4
            schema:
              $ref: "#/components/schemas/Handles"
      responses:
        '200':
          description: Success. The body contains status of requested handles.
          content:
            'application/json':
              example:
                resources:
                  - statusCode: 5000
                    status: closed
              schema:
                $ref: "#/components/schemas/Resources"
        '500':
          description: An internal error occurred. The message will give details.
          content:
            'application/json':
              example:
                error:
                  code: 500
                  msg: "failed to handle request: ..."
              schema:
                $ref: "#/components/schemas/Error"
        '400':
          description: The incoming request was malformed.
          content:
            'application/json':
              example:
                error:
                  code: 400
                  msg: "failed to decode request body: ..."
              schema:
                $ref: "#/components/schemas/Error"
  /api/resource/v1/status:
    post:
      description: Used to query preparation status. Requires handles from a previous request.
      tags:
        - Query
      requestBody:
        content:
          application/json:
            example:
              handles:
                - name: 21691aef7ba3bafb85b596e109627de97ed8e87d
                  clusterID: cluster-installation-0
                  signature: 304402204558f9424c6052560270fbeaee78885da83c3f822252f05cfb3410d9dc6760620220586b22c6443d145ac2a33b1bb35ad4555b17d6980bf335ee9058b38b3f0f54df-1661258177-4
            schema:
              $ref: "#/components/schemas/Handles"
      responses:
        '200':
          description: Success. The body contains status of requested handles.
          content:
            'application/json':
              example:
                resources:
                  - statusCode: 5000
                    status: closed
              schema:
                $ref: "#/components/schemas/Resources"
        '500':
          description: An internal error occurred. The message will give details.
          content:
            'application/json':
              example:
                error:
                  code: 500
                  msg: "failed to handle request: ..."
              schema:
                $ref: "#/components/schemas/Error"
        '400':
          description: The incoming request was malformed.
          content:
            'application/json':
              example:
                error:
                  code: 400
                  msg: "failed to decode request body: ..."
              schema:
                $ref: "#/components/schemas/Error"
tags:
  - name: Request
  - name: Query
components:
  schemas:
    Elements:
      type: object
      properties:
        elements:
          type: array
          items:
            type: object
            properties:
              uri:
                type: string
                description: "URL or URN of the resource to prepare."
              mimeType:
                type: string
                description: "Optional type override. Set only if necessary."
                default: ""
              ignoreCache:
                type: boolean
                description: "Optional override whether to force preparation even if results are already present."
                default: false
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: integer
              description: The HTTP status code. The status code is also set for the response itself.
            msg:
              type: string
              description: A message detailing what went wrong.
    Handles:
      type: object
      properties:
        handles:
          type: array
          description: The list of handles which can be used to perform status checks. Order is the same as request order.
          items:
            type: object
            properties:
              name:
                type: string
                description: Identifier of the internal resource.
              clusterID:
                type: string
                description: Identifier of the internal instant3Dhub instance.
              signature:
                type: string
                description: Security signature to access the internal resource.
    Resources:
      type: object
      properties:
        resources:
          type: array
          items:
            type: object
            properties:
              statusCode:
                type: integer
                enum: [ 1000, 1001, 1002, 3000, 5000, 5001, 6000, 6001, 8001, 8002, 9000, 9001, 9002, 9003 ]
                description: "Internal status code of the requested resource. Divide by 1000 to get a category of the following: 1: Init, 3: Working, 5: FinishedSuccess, 6: FinishedFailure, 8: SystemErrorRetryable, 9: SystemErrorFinal"
              status:
                type: string
                enum: [ queued, progress, closed, warning, error ]
                description: "Simplified status of the resource."