openapi: "3.0.0"
info: 
  version: 0.0.4
  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'
# Check 2xx, 4xx, 5xx...            
        '401':
          $ref: '#/components/responses/UUID'
    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/{trackableUUID}:
    get:
      summary: Find a trackable by its UUID
      operationId: getTrackableById
      tags:
      - trackables
      parameters:
        - name: trackableUUID
          in: path
          description: UUID 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 UUID supplied
        '404':
          description: Trackable not found
    delete:
      summary: Deletes a trackable
      operationId: deleteTrackable
      tags:
      - trackables
      parameters:
        - name: trackableUUID
          in: path
          description: trackable UUID to delete
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
        '400':
          description: Invalid UUID 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/{worldAnchorUUID}:
    get:
      summary: Find a world anchor by his UUID
      operationId: getWorldAnchorById
      tags:
      - world anchors
      parameters:
        - name: trackableUUID
          in: path
          description: UUID 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 UUID supplied
        '404':
          description: World Anchor not found
    delete:
      summary: Deletes a world anchor
      operationId: deleteWorldAnchor
      tags:
      - world anchors
      parameters:
        - name: trackableUUID
          in: path
          description: world anchor UUID to delete
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
        '400':
          description: Invalid UUID 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/{worldLinkUUID}:
    get:
      summary: Find a link by his ID
      operationId: getWorldLinkById
      tags:
      - world links
      parameters:
        - name: worldLinkUUID
          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: worldLinkUUID
          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:
        - creatorUUID
        - trackableType
        - trackableEncodingInformation
        - trackablePayload
        - localCRS
        - unit
        - trackableSize
        - keyvalueTagList
      properties:
        UUID:
          description: A Universally Unique IDentifier identifying the trackable (RFC 4122)
          type: string
          format: uuid
          example: fa8bbe40-8052-11ec-a8a3-0242ac120002
        creatorUUID:        
          description: A Universally Unique IDentifier identifying the creator of the trackable (a person, a team or a company)
          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:         
          $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:
            $ref: '#/components/schemas/Transform3D'
        unit:
            $ref: '#/components/schemas/UnitSystem'
        trackableSize:
            $ref: '#/components/schemas/Size'
        keyvalueTags:
            $ref: '#/components/schemas/KeyvalueTagList'
    WorldAnchor:
      type: object
      required:
        - creatorUUID        
        - localCRS
        - unit
        - worldAnchorSize
        - keyvalueTagList
      properties:
        UUID:
          description: A Universally Unique IDentifier identifying the world anchor
          type: string
          format: uuid
          example: ce8ccd80-56ee-2a5c-a8a3-0242ac150d002
        creatorUUID:
          description: A Universally Unique IDentifier identifying the creator of the world anchor
          type: string
          format: uuid
          example: c75f6324-77a0-11ec-90d6-0242ac120003
        localCRS:
            $ref: '#/components/schemas/Transform3D'
        unit:
            $ref: '#/components/schemas/UnitSystem'
        worldAnchorSize:
            $ref: '#/components/schemas/Size'
        keyvalueTags:
            $ref: '#/components/schemas/KeyvalueTagList'
    WorldLink:
      type: object
      required:
        - creatorUUID
        - UUIDFrom
        - UUIDTo
        - transform
        - unit
        - linkSize
        - keyvalueTags
      properties:
        UUID:
          description: A Universally Unique IDentifier identifying the link
          type: string
          format: uuid
          example: ce8ccd80-56ee-2a5c-a8a3-0242ac150d002
        creatorUUID:
          description: A Universally Unique IDentifier identifying the creator of the link
          type: string
          format: uuid
          example: c75f6324-77a0-11ec-90d6-0242ac120003
        UUIDFrom:
          description: A Universally Unique IDentifier identifying a world anchor or trackable
          type: string
          format: uuid
          example: ce8ccd80-56ee-2a5c-a8a3-0242ac150d002
        UUIDTo:
          description: A Universally Unique IDentifier identifying a world anchor or trackable
          type: string
          format: uuid
          example: ce8ccd80-56ee-2a5c-a8a3-0242ac150d002    
        transform:
            $ref: '#/components/schemas/Transform3D'
        unit:
            $ref: '#/components/schemas/UnitSystem'
        linkSize:
            $ref: '#/components/schemas/Size'
        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"
    Transform3D:
        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
        example: [-2, 1,-3, 4,
                   4, 4, 4, 2,
                   1, 0,-2, 1,
                  -1,-2, 0, 0]
    UnitSystem:
        description: Unit of length
        type: string
        enum: [MM,  CM,  DM,  M,  DAM,  HM,  KM,  INCH, FOOT, YARD, MILE]
        example: M
    Size:
        description: Size {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