openapi: "3.0.0"
info: 
  version: 0.0.3
  title: World Storage API
  description: API ensuring interoperability between an authoring tool and a World Storage service
  license:
    name: BSD-3-clause
    url: https://opensource.org/licenses/BSD-3-Clause
servers:
  - url: http://localhost:8080
paths:
  /ping:
    get:
      summary: Test the server availability
      responses:
        '200':
          description: OK
  /admin:
    get:
      summary: Get the version of the API
      operationId: getVersion
      responses:
        '200':
          description: OK world storage.
          content:
            text/plain:
              schema: 
                type: string           
  /trackables:
    post:
      summary: Create a trackable
      operationId: addTrackable
      tags:
        - trackables
      requestBody:
          description: the trackable to be added to the world storage
          required: true
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Trackable'
            application/xml:
              schema:
                $ref: '#/components/schemas/Trackable'
      responses:
        '200':
          description: OK returns the UUID of the Trackable defined by the world storage.
          content:
            text/plain:
              schema: 
                type: string            
        '201':
          description: Null response
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    get:
      summary: returns the list of all trackables defined by the world storage.
      operationId: getTrackables
      tags:
        - trackables
      responses:
        200:
          description: OK returns all the Trackables defined by the world storage.
          content:
            application/json:
              schema:
                type : array
                items :
                  $ref: "#/components/schemas/Trackable"          
        201:
          description: Null response
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"    
  /trackables/{trackableId}:
    get:
      summary: Find a trackable by his ID
      operationId: getTrackableById
      tags:
      - trackables
      parameters:
        - name: trackableId
          in: path
          description: ID of the trackable to retrieve
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Trackable' 
        '400':
          description: Invalid ID supplied
        '404':
          description: Trackable not found
    delete:
      summary: Deletes a trackable
      operationId: deleteTrackable
      tags:
      - trackables
      parameters:
        - name: trackableId
          in: path
          description: trackable id to delete
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
        '400':
          description: Invalid ID supplied
        '404':
          description: trackable not found              
  /worldAnchors:
    post:
      summary: Create a world anchor
      operationId: addWorldAnchor
      tags:
        - world anchors
      requestBody:
          description: the world anchor to be added to the world storage
          required: true
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorldAnchor'             
            application/xml:
              schema:
                $ref: '#/components/schemas/WorldAnchor'
      responses:
        '200':
          description: OK returns the UUID of the World Anchor defined by the world storage.
          content:
            text/plain:
              schema: 
                type: string            
        '201':
          description: Null response
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'  
    get:
      summary: returns the list of all world anchors defined by the world storage.
      operationId: getWorldAnchors
      tags:
        - world anchors
      responses:
        200:
          description: OK returns all the world anchors defined by the world storage.
          content:
            application/json:
              schema:
                type : array
                items :
                  $ref: "#/components/schemas/WorldAnchor"          
        201:
          description: Null response
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"  
  /worldAnchors/{worldAnchorId}:
    get:
      summary: Find a world anchor by his ID
      operationId: getWorldAnchorById
      tags:
      - world anchors
      parameters:
        - name: worldAnchorId
          in: path
          description: ID of the world anchor to retrieve
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorldAnchor' 
        '400':
          description: Invalid ID supplied
        '404':
          description: World Anchor not found
    delete:
      summary: Deletes a world anchor
      operationId: deleteWorldAnchor
      tags:
      - world anchors
      parameters:
        - name: worldAnchorId
          in: path
          description: world anchor id to delete
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
        '400':
          description: Invalid ID supplied
        '404':
          description: World anchor not found
  /worldLinks:
    post:
      summary: Create a link between world anchors and trackables
      operationId: addWorldLink
      tags:
        - world links
      requestBody:
          description: the link to be added to the world storage
          required: true
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorldLink'
            application/xml:
              schema:
                $ref: '#/components/schemas/WorldLink'
      responses:
        '200':
          description: OK returns the UUID of the link defined by the world storage.
          content:
            text/plain:
              schema: 
                type: string            
        '201':
          description: Null response
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'  
    get:
      summary: returns the list of all links defined by the world storage.
      operationId: getWorldLinks
      tags:
        - world links
      responses:
        200:
          description: OK returns all the worldLinks defined by the world storage.
          content:
            application/json:
              schema:
                type : array
                items :
                  $ref: "#/components/schemas/WorldLink"          
        201:
          description: Null response
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /worldLinks/{linkId}:
    get:
      summary: Find a link by his ID
      operationId: getWorldLinkById
      tags:
      - world links
      parameters:
        - name: worldLinkId
          in: path
          description: ID of the link to retrieve
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorldLink' 
        '400':
          description: Invalid ID supplied
        '404':
          description: World Link not found
    delete:
      summary: Deletes a worldLink
      operationId: deleteWorldLink
      tags:
      - world links
      parameters:
        - name: linkId
          in: path
          description: link id to delete
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
        '400':
          description: Invalid ID supplied
        '404':
          description: link not found
components:
  schemas:
    Trackable:
      type: object
      required:
        - creatorUID
        - trackableType
        - trackableEncodingInformation
        - trackablePayload
        - localCRS
        - unit
        - trackableDimension
        - keyvalueTagList
      properties:
        UID:
          description: A Universally Unique IDentifier identifying the trackable
          type: string
          format: uuid
          example: fa8bbe40-8052-11ec-a8a3-0242ac120002
        creatorUID:
          description: A Universally Unique IDentifier identifying the creator of the trackable
          type: string
          format: uuid
          example: c75f6324-77a0-11ec-90d6-0242ac120003
        trackableType:
          description: Extensible list of trackable types possibly handled by complient World Storage implementation
          type: string
          enum: [FIDUCIAL_MARKER, IMAGE_MARKER, MAP, OTHER]
          example: FIDUCIAL_MARKER
        trackableEncodingInformation:         
          description: Identifies targeted framework and version of the format.
          $ref: '#/components/schemas/EncodingInformationStructure'
        trackablePayload:
          description: The data provided to create the trackable in a specific format handled by the World Storage service.
          type: string
          format: byte
          example: "10110101"
        localCRS:
            description: Coordinate reference system 
            $ref: '#/components/schemas/CRS'
            example: [-2,  1,  -3, 4,
                    4,   4,  4,  2,
                    1,   0,  -2, 1,
                    -1,  -2, 0,  0]
        unit:
            description: Unit of length
            $ref: '#/components/schemas/UnitSystem'
        trackableDimension:
            description: Bounding box of the Trackable, {width, length, 0} for 2D trackables, {width, length, depth} for 3D trackables
            $ref: '#/components/schemas/Dimension'
            example: [1,5,0]
        keyvalueTags:
            description: List of additional parameters to be stored
            $ref: '#/components/schemas/KeyvalueTagList'
            example: { "author" : ["james","donovan"], "image" : ["skater"]}
    WorldAnchor:
      type: object
      required:
        - creatorUID        
        - localCRS
        - unit
        - worldAnchorDimension
        - keyvalueTagList
      properties:
        UID:
          description: A Universally Unique IDentifier identifying the world anchor
          type: string
          format: uuid
          example: ce8ccd80-56ee-2a5c-a8a3-0242ac150d002
        creatorUID:
          description: A Universally Unique IDentifier identifying the creator of the world anchor
          type: string
          format: uuid
          example: c75f6324-77a0-11ec-90d6-0242ac120003
        localCRS:
            description: Coordinate reference system 
            $ref: '#/components/schemas/CRS'
            example: [-2,  1,  -3, 4,
                    4,   4,  4,  2,
                    1,   0,  -2, 1,
                    -1,  -2, 0,  0]
        unit:
            description: Unit of length
            $ref: '#/components/schemas/UnitSystem'
        worldAnchorDimension:
            description: Bounding box {width, length, depth}
            $ref: '#/components/schemas/Dimension'
            example: [1,5,0]
        keyvalueTags:
            description: List of additional parameters to be stored
            $ref: '#/components/schemas/KeyvalueTagList'
            example: { "Place" : ["Museum 1"], "room" : ["B4"]}   
    WorldLink:
      type: object
      required:
        - creatorUID
        - UIDA
        - UIDB
        - localCRS
        - unit
        - linkDimension
        - keyvalueTags
      properties:
        UID:
          description: A Universally Unique IDentifier identifying the link
          type: string
          format: uuid
          example: ce8ccd80-56ee-2a5c-a8a3-0242ac150d002
        creatorUID:
          description: A Universally Unique IDentifier identifying the creator of the link
          type: string
          format: uuid
          example: c75f6324-77a0-11ec-90d6-0242ac120003
        UIDA:
          description: A Universally Unique IDentifier identifying a world anchor or trackable
          type: string
          format: uuid
          example: ce8ccd80-56ee-2a5c-a8a3-0242ac150d002
        UIDB:
          description: A Universally Unique IDentifier identifying a world anchor or trackable
          type: string
          format: uuid
          example: ce8ccd80-56ee-2a5c-a8a3-0242ac150d002    
        localCRS:
            description: Coordinate reference system 
            $ref: '#/components/schemas/CRS'
            example: [-2,  1,  -3, 4,
                    4,   4,  4,  2,
                    1,   0,  -2, 1,
                    -1,  -2, 0,  0]
        unit:
            description: Unit of length
            $ref: '#/components/schemas/UnitSystem'
            example: M
        linkDimension:
            description: Bounding box
            $ref: '#/components/schemas/Dimension'
            example: [1,5,0]
        keyvalueTags:
            description: List of additional parameters to be stored
            $ref: '#/components/schemas/KeyvalueTagList'
            example: { "LinkType" : ["Hierarchy"]}          
    EncodingInformationStructure:
      required:
        - dataFormat
        - version
      properties:
        dataFormat:
          description: Identifier of the target framework
          type: string
          enum: [HOLOLENS, ARKIT, ARCORE]
          example : "HOLOLENS"
        version:
          description: The version of the format
          type: string
          example : "1.01"
    CRS:
        description: Coordinate reference system of the world anchor, a 4*4 matrix (rowmajor) represented by a float vector
        type: array
        minItems: 16
        maxItems: 16
        items:
            type: number
            format: float
    UnitSystem:
        description: Unit of length
        type: string
        enum: [MM,  CM,  DM,  M,  DAM,  HM,  KM,  INCH, FOOT, YARD, MILE]
    Dimension:
        description: Bounding box {width, length, depth}
        type: array
        items:
            type: number
            format: double
        minItems: 3
        maxItems: 3
        example: [1,5,0]          
    KeyvalueTagList:   
        description: List of additional parameters to be stored with the trackable.
        type: object
        additionalProperties:
            type: array
            items:
                type: string
            minItems: 1
        example: { "Place" : ["Museum 1"], "room" : ["B4"]} 
    Error:
      required:
        - code
        - message
      properties:
        code:
          type: integer
          format: int32
        message:
          type: string