openapi: "3.0.3"
info:
  title: "3DSpaces API"
  description: This API is still in an <style="color:red">EXPERIMENTAL</style> state and subject to change.
  contact:
    name: Threedy GmbH
    url: https://www.threedy.io/
    email: contact@threedy.io
  version: "3.1"
servers:
  - url: "http://192.168.210.237:21600"
    description: Testing server
paths:
  /space:
    post:
      deprecated: true
      description: Used to create a space with a randomly generated id in the 'default' namespace.
      tags:
        - Create
      responses:
        '200':
          description: Success
          content:
            'application/json':
              example:
                spaceID: default/a72efb04-8121-4d66-99f9-6b34e53e92d6
              schema:
                type: object
                properties:
                  spaceID:
                    type: string
                    description: This is the unique namespace/id combination to address the created space in all other calls. It uses the default namespace and randomly generates a uuid as the id.
                    pattern: "^default/[a-f0-9\\-]+$"
        '500':
          description: This can occur if requesting a session handler or encoding the response message fails.
          content:
            "text/plain; charset=utf-8":
              example: "failed to encode create space reply: ..."
  /space/{namespace}:
    post:
      deprecated: true
      description: Used to create a space with a randomly generated id in the given namespace.
      tags:
        - Create
      parameters:
        - name: namespace
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/Namespace"
      responses:
        '200':
          description: Success
          content:
            'application/json':
              example:
                spaceID: myNamespace/a72efb04-8121-4d66-99f9-6b34e53e92d6
              schema:
                type: object
                properties:
                  spaceID:
                    type: string
                    description: This is the unique namespace/id combination to address the created space in all other calls. It uses the namespace specified in the path and randomly generates a uuid as the id.
                    pattern: "{namespace}/[a-f0-9\\-]+"
        '400':
          description: Check for path parameters failed.
          content:
            "text/plain; charset=utf-8":
              example: "parameters are missing in path, expected: /space/{namespace}"
        '500':
          description: This can occur if requesting a session handler or encoding the response message fails.
          content:
            "text/plain; charset=utf-8":
              example: "failed to encode create space reply: ..."
  /space/{namespace}/{id}:
    post:
      deprecated: true
      description: Used to create a space with the given id in the given namespace.
      tags:
        - Create
      parameters:
        - name: namespace
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/Namespace"
        - name: id
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/ID"
      responses:
        '200':
          description: Success
          content:
            'application/json':
              example:
                spaceID: myNamespace/myID
              schema:
                type: object
                properties:
                  spaceID:
                    type: string
                    description: This is the unique namespace/id combination to address the created space in all other calls. It uses the parameters specified in the path.
                    pattern: "{namespace}/{id}"
        '400':
          description: Check for path parameters failed.
          content:
            "text/plain; charset=utf-8":
              example: "parameters are missing in path, expected: /space/{namespace}/{id}"
        '500':
          description: This can occur if requesting a session handler or encoding the response message fails.
          content:
            "text/plain; charset=utf-8":
              example: "failed to encode create space reply: ..."
    get:
      deprecated: true
      description: Redirects to WebVis with the given spaceID as a starting parameter.
      tags:
        - Load
      parameters:
        - name: namespace
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/Namespace"
        - name: id
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/ID"
      responses:
        '302':
          description: Redirect to WebVis with spaceID.
        '400':
          description: Check for path parameters failed.
          content:
            "text/plain; charset=utf-8":
              example: "parameters are missing in path, expected: /space/{namespace}/{id}"
  /space/{namespace}/{id}/add:
    post:
      deprecated: true
      description: Used to add a model to the given space.
      tags:
        - Modify
      parameters:
        - name: namespace
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/Namespace"
        - name: id
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/ID"
        - name: parent
          in: query
          schema:
            $ref: "#/components/schemas/NodeID"
        - name: root
          in: query
          schema:
            type: string
            example: /path/to/entryFile.plmxml
        - name: label
          in: query
          schema:
            type: string
            description: The label for the node in the instance graph.
            example: myNode
      requestBody:
        description: The body contains either a link to a 3D model that should be added or uploads a 3D model or archive.
        required: true
        content:
          application/json:
            example:
              url: "urn:x-i3d:shape:sphere"
            schema:
              type: object
              properties:
                url:
                  type: string
                  description: The link to a 3D model that should be added.
          multipart/form-data:
            schema:
              type: object
              properties:
                fileName:
                  type: string
                  description: A 3D model file or an archive (.zip, .tar, .tar.gz/.tgz). If an archive is uploaded the root query parameter is not optional!
                  format: binary
      responses:
        '200':
          description: Successfully added the model to the instance graph addressable by the returned 'nodeID'.
          content:
            'application/json':
              example:
                nodeID: 1
                transactionId: 6
              schema:
                type: object
                properties:
                  nodeID:
                    $ref: "#/components/schemas/NodeID"
        '400':
          description: An error related to the parameters given.
          content:
            "text/plain; charset=utf-8":
              example: url is missing in body
        '500':
          description: Something failed internally while processing the add call.
          content:
            "text/plain; charset=utf-8":
              example: "failed to do upload request: ..."
  /space/{namespace}/{id}/setProperty:
    post:
      deprecated: true
      description: Used to change the property of the given nodes in the space.
      tags:
        - Modify
      parameters:
        - name: namespace
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/Namespace"
        - name: id
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/ID"
      requestBody:
        description: The body contains the information about the property and its value that should be set and the affected nodes.
        required: true
        content:
          application/json:
            example:
              nodeID:
                - 1
              property: "enabled"
              value: true
            schema:
              type: object
              properties:
                nodeIDs:
                  type: array
                  description: The affected nodes.
                  items:
                    type: integer
                property:
                  type: string
                  description: The property that should be set.
                value:
                  description: The new value assigned for the given property.
      responses:
        '200':
          description: Success in setting the property of the given 'nodeIDs'.
        '400':
          description: An error related to the parameters given.
          content:
            "text/plain; charset=utf-8":
              example: "failed to decode request body: ..."
        '500':
          description: Something failed internally while processing the setProperty call.
          content:
            "text/plain; charset=utf-8":
              example: "failed to do setProperty: ..."
  /api/space/v1:
    post:
      description: Used to create a space with a randomly generated id in the 'default' namespace.
      tags:
        - Create
      responses:
        '200':
          description: Success
          content:
            'application/json':
              example:
                spaceID: default/a72efb04-8121-4d66-99f9-6b34e53e92d6
              schema:
                type: object
                properties:
                  spaceID:
                    type: string
                    description: This is the unique namespace/id combination to address the created space in all other calls. It uses the default namespace and randomly generates a uuid as the id.
                    pattern: "^default/[a-f0-9\\-]+$"
        '500':
          description: This can occur if requesting a session handler or encoding the response message fails.
          content:
            "text/plain; charset=utf-8":
              example: "failed to encode create space reply: ..."
  /api/space/v1/{namespace}:
    post:
      description: Used to create a space with a randomly generated id in the given namespace.
      tags:
        - Create
      parameters:
        - name: namespace
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/Namespace"
      responses:
        '200':
          description: Success
          content:
            'application/json':
              example:
                spaceID: myNamespace/a72efb04-8121-4d66-99f9-6b34e53e92d6
              schema:
                type: object
                properties:
                  spaceID:
                    type: string
                    description: This is the unique namespace/id combination to address the created space in all other calls. It uses the namespace specified in the path and randomly generates a uuid as the id.
                    pattern: "{namespace}/[a-f0-9\\-]+"
        '400':
          description: Check for path parameters failed.
          content:
            "text/plain; charset=utf-8":
              example: "parameters are missing in path, expected: /space/{namespace}"
        '500':
          description: This can occur if requesting a session handler or encoding the response message fails.
          content:
            "text/plain; charset=utf-8":
              example: "failed to encode create space reply: ..."
  /api/space/v1/{namespace}/{id}:
    post:
      description: Used to create a space with the given id in the given namespace.
      tags:
        - Create
      parameters:
        - name: namespace
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/Namespace"
        - name: id
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/ID"
      responses:
        '200':
          description: Success
          content:
            'application/json':
              example:
                spaceID: myNamespace/myID
              schema:
                type: object
                properties:
                  spaceID:
                    type: string
                    description: This is the unique namespace/id combination to address the created space in all other calls. It uses the parameters specified in the path.
                    pattern: "{namespace}/{id}"
        '400':
          description: Check for path parameters failed.
          content:
            "text/plain; charset=utf-8":
              example: "parameters are missing in path, expected: /space/{namespace}/{id}"
        '500':
          description: This can occur if requesting a session handler or encoding the response message fails.
          content:
            "text/plain; charset=utf-8":
              example: "failed to encode create space reply: ..."
    get:
      description: Redirects to WebVis with the given spaceID as a starting parameter.
      tags:
        - Load
      parameters:
        - name: namespace
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/Namespace"
        - name: id
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/ID"
      responses:
        '302':
          description: Redirect to WebVis with spaceID.
        '400':
          description: Check for path parameters failed.
          content:
            "text/plain; charset=utf-8":
              example: "parameters are missing in path, expected: /space/{namespace}/{id}"
  /api/space/v1/{namespace}/{id}/add:
    post:
      description: Used to add a model to the given space.
      tags:
        - Modify
      parameters:
        - name: namespace
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/Namespace"
        - name: id
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/ID"
        - name: parent
          in: query
          schema:
            $ref: "#/components/schemas/NodeID"
        - name: root
          in: query
          schema:
            type: string
            example: /path/to/entryFile.plmxml
        - name: label
          in: query
          schema:
            type: string
            description: The label for the node in the instance graph.
            example: myNode
      requestBody:
        description: The body contains either a link to a 3D model that should be added or uploads a 3D model or archive.
        required: true
        content:
          application/json:
            example:
              url: "urn:x-i3d:shape:sphere"
            schema:
              type: object
              properties:
                url:
                  type: string
                  description: The link to a 3D model that should be added.
          multipart/form-data:
            schema:
              type: object
              properties:
                fileName:
                  type: string
                  description: A 3D model file or an archive (.zip, .tar, .tar.gz/.tgz). If an archive is uploaded the root query parameter is not optional!
                  format: binary
      responses:
        '200':
          description: Successfully added the model to the instance graph addressable by the returned 'nodeID'.
          content:
            'application/json':
              example:
                nodeID: 1
                transactionId: 6
              schema:
                type: object
                properties:
                  nodeID:
                    $ref: "#/components/schemas/NodeID"
        '400':
          description: An error related to the parameters given.
          content:
            "text/plain; charset=utf-8":
              example: url is missing in body
        '500':
          description: Something failed internally while processing the add call.
          content:
            "text/plain; charset=utf-8":
              example: "failed to do upload request: ..."
  /api/space/v1/{namespace}/{id}/setProperty:
    post:
      description: Used to change the property of the given nodes in the space.
      tags:
        - Modify
      parameters:
        - name: namespace
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/Namespace"
        - name: id
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/ID"
      requestBody:
        description: The body contains the information about the property and its value that should be set and the affected nodes.
        required: true
        content:
          application/json:
            example:
              nodeIDs:
                - 1
              property: "enabled"
              value: true
            schema:
              type: object
              properties:
                nodeIDs:
                  type: array
                  description: The affected nodes.
                  items:
                    type: integer
                property:
                  type: string
                  description: The property that should be set.
                value:
                  description: The new value assigned for the given property.
      responses:
        '200':
          description: Success in setting the property of the given 'nodeIDs'.
        '400':
          description: An error related to the parameters given.
          content:
            "text/plain; charset=utf-8":
              example: "failed to decode request body: ..."
        '500':
          description: Something failed internally while processing the setProperty call.
          content:
            "text/plain; charset=utf-8":
              example: "failed to do setProperty: ..."
tags:
  - name: Create
  - name: Load
  - name: Modify
components:
  schemas:
    Namespace:
      type: string
      description: Identifies a group of spaces.
      example: myNamespace
      pattern: "^[^\\.\\/\\{\\};]+$"
    ID:
      type: string
      description: Identifies a space inside a namespace. Needs to be unique per namespace.
      example: myID
      pattern: "^[^\\.\\/\\{\\};]+$"
    NodeID:
      type: integer
      description: Identifies a node in the instance graph.
      default: 0
      minimum: 0