openapi.yaml

# Copyright 2022 ETSI. Licensed under the BSD-3-Clause license
# API for the Augmented Reality Framework (ARF)
# Working group: ETSI ISG ARF
# STF group: STF620 (validation)
#
# References:
# - Explaination UUID: https://en.wikipedia.org/wiki/Universally_unique_identifier / https://fr.wikipedia.org/wiki/Universally_unique_identifier
# - UUID formats: 8-4-4-4-12 format string, lower case (but case insensitive on input) 
# - UUID RFC4122: https://datatracker.ietf.org/doc/html/rfc4122#section-3
# - online UUID generator: https://www.uuidgenerator.net/
# - Rules for RESTful error code RFC2616: https://datatracker.ietf.org/doc/html/rfc2616#section-10
# - Guide: https://restfulapi.net/http-status-codes/
#
# Last Version: 01.06.2022

openapi: "3.0.0"

info: 
  version: 1.0.0
  title: World Storage API
  description: API ensuring interoperability between an authoring tool and a World Storage service
  license:
    name: Copyright 2022 ETSI. Licensed under the BSD-3-Clause license
    url: https://opensource.org/licenses/BSD-3-Clause
servers:
  - url: http://localhost:8080
  
tags:
  - name: default
    description: Default operations to test the current server's state
  - name: Trackables
    description: Trackables are models of parts of the real world. <br>Trackables are elements of the real world of which features are available and/or could be extracted.<br> Trackables provide a Coordinate Reference System in which a pose can be expressed.
  - name: World Anchors
    description: A World Anchor represents a fixed position in relation to one or more elements of the real world. <br>It has a Coordinate Reference System in which AR Assets stay spatially-registered. 
  - name: World Links
    description: A World Link represents and defines the relative 3D position and orientation between elements (Trackables and/or World Anchors).
  
paths:
  /ping:
    get:
      summary: Test the server availability.
      operationId: getPing
      responses:
        '200':
          description: Ok, returns a string message.
          content:
            text/plain:
              schema:
                type: string
                example: "pong"
  /admin:
    get:
      summary: Get the state of the server.
      operationId: getAdmin
      responses:
        '200':
          description: OK, world storage server ready.
          content:
            text/plain:
              schema:
                type: string
                example: "Server up and running"
  /version:
    get:
      summary: Get the version of the ARF API.
      operationId: getVersion
      responses:
        '200':
          description: Current version.
          content:
            text/plain:
              schema:
                type: string
                example: "1.0.0"

##############
# TRACKABLES #
##############
  /trackables:
    post:
      summary: Create a Trackable.
      operationId: addTrackable
      description: Create a new Trackable from a json object containing all the required informations and add it to the world storage. <br>As a result you will get the ID of the newly created Trackable.
      tags:
        - Trackables
      requestBody:
          description: The Trackable to be added to the world storage.
          required: true
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Trackable'
      responses:
        '200':
          description: OK, return the UUID of the Trackable defined by the world storage.
          content:
            text/plain:
              schema:
                type: string
                example: "777266da-e286-11ec-8fea-0242ac120002"
        '201':
          description: Null response.
          content:
            text/plain:
              schema:
                type: string
                example: ""
        '400':
          $ref: '#/components/responses/400_BadRequest'
        '409': 
          $ref: '#/components/responses/409_NotEmptyUUID'
        'default':
          $ref: '#/components/responses/4xx_UnexpectedError'
    put:
      summary: Modify a Trackable.
      operationId: modifyTrackable
      description: Modify an existing Trackable given a json object containing all the required informations. <br> **Please note that ID of the object is required in the JSON**
      tags:
        - Trackables
      requestBody:
          description: The Trackable to be modified in the world storage.
          required: true
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Trackable'
      responses:
        '200':
          description: OK, return the UUID of the modified Trackable.
          content:
            text/plain:
              schema:
                type: string
                example: "777266da-e286-11ec-8fea-0242ac120002"
        '400':
          $ref: '#/components/responses/400_BadRequest'
        '404': 
          $ref: '#/components/responses/404_NotFoundUUID'
        'default':
          $ref: '#/components/responses/4xx_UnexpectedError'
    get:
      summary: Return all the Trackables.
      operationId: getTrackables
      description: Get all the Trackables currently being stored in the world storage.
      tags:
        - Trackables
      responses:
        '200':
          description: OK, return all the Trackables defined by the world storage.
          content:
            application/json:
              schema:
                type : array
                items :
                  $ref: "#/components/schemas/Trackable"          
        '201':
          description: Null response.
          content:
            text/plain:
              schema:
                type: string
                example: ""
        default:
          $ref: '#/components/responses/4xx_UnexpectedError'

  /trackables/{trackableUUID}:
    get:
      summary: Find a Trackable by its UUID.
      operationId: getTrackableById
      description: Get a single Trackable stored in the world storage from its ID.
      tags:
      - Trackables
      parameters:
        - name: trackableUUID
          in: path
          description: UUID of the Trackable to retrieve.
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Successful operation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Trackable' 
        '400':
          $ref: '#/components/responses/400_InvalidUUID'
        '404':
          $ref: '#/components/responses/404_NotFoundUUID'
    delete:
      summary: Delete a Trackable.
      operationId: deleteTrackable
      description: Delete a single Trackable stored in the world storage from its ID.
      tags:
      - Trackables
      parameters:
        - name: trackableUUID
          in: path
          description: Trackable UUID to delete.
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: OK, delete successful.
          content:
            text/plain:
              schema:
                type: string
                example: "Element succesfully deleted"
        '400':
          $ref: '#/components/responses/400_InvalidUUID'
        '404':
          $ref: '#/components/responses/404_NotFoundUUID'   

#################
# WORLD ANCHORS #
#################
  /worldAnchors:
    post:
      summary: Create a World Anchor.
      operationId: addWorldAnchor
      description: Create a new World Anchor from a json object containing all the required informations and add it to the world storage. <br>As a result you will get the ID of the newly created World Anchor.
      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'
      responses:
        '200':
          description: OK, return the UUID of the World Anchor defined by the world storage.
          content:
            text/plain:
              schema:
                type: string    
                example: "777266da-e286-11ec-8fea-0242ac120002"
        '201':
          description: Null response.
          content:
            text/plain:
              schema:
                type: string
                example: ""
        '400':
          $ref: '#/components/responses/400_BadRequest'
        '409': 
          $ref: '#/components/responses/409_NotEmptyUUID'
        'default':
          $ref: '#/components/responses/4xx_UnexpectedError'
    put:
      summary: Modify a World Anchor.
      operationId: modifyWorldAnchor
      description: Modify an existing World Anchor given a json object containing all the required informations. <br> **Please note that ID of the object is required in the JSON**
      tags:
        - World Anchors
      requestBody:
          description: The World Anchor to be modified in the world storage.
          required: true
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorldAnchor'
      responses:
        '200':
          description: OK, return the UUID of the modified World Anchor.
          content:
            text/plain:
              schema:
                type: string
                example: "777266da-e286-11ec-8fea-0242ac120002"
        '400':
          $ref: '#/components/responses/400_BadRequest'
        '404': 
          $ref: '#/components/responses/404_NotFoundUUID'
        'default':
          $ref: '#/components/responses/4xx_UnexpectedError'
    get:
      summary: Return all the World Anchors.
      operationId: getWorldAnchors
      description: Get all the World Anchors currently being stored in the world storage.
      tags:
        - World Anchors
      responses:
        '200':
          description: OK, return all the World Anchors defined by the world storage.
          content:
            application/json:
              schema:
                type : array
                items :
                  $ref: "#/components/schemas/WorldAnchor"          
        '201':
          description: Null response.
          content:
            text/plain:
              schema:
                type: string
                example: ""
        default:
          $ref: '#/components/responses/4xx_UnexpectedError'

  /worldAnchors/{worldAnchorUUID}:
    get:
      summary: Find a World Anchor by its UUID.
      operationId: getWorldAnchorById
      description: Get a single World Anchor stored in the world storage from its ID.
      tags:
      - World Anchors
      parameters:
        - name: worldAnchorUUID
          in: path
          description: UUID of the World Anchor to retrieve.
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Successful operation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorldAnchor' 
        '400':
          $ref: '#/components/responses/400_InvalidUUID'
        '404':
          $ref: '#/components/responses/404_NotFoundUUID'
    delete:
      summary: Delete a World Anchor.
      operationId: deleteWorldAnchor
      description: Delete a single World Anchor stored in the world storage from its ID.
      tags:
      - World Anchors
      parameters:
        - name: worldAnchorUUID
          in: path
          description: World Anchor UUID to delete.
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: OK, delete successful.
          content:
            text/plain:
              schema:
                type: string
                example: "Element succesfuly deleted"
        '400':
          $ref: '#/components/responses/400_InvalidUUID'
        '404':
          $ref: '#/components/responses/404_NotFoundUUID'   

###############
# WORLD LINKS #
###############
  /worldLinks:
    post:
      summary: Create a World Link between elements (world anchors and/or trackables).
      operationId: addWorldLink
      description: Create a new World Link from a json object containing all the required informations and add it to the world storage. <br>As a result you will get the ID of the newly created World Link.
      tags:
        - World Links
      requestBody:
          description: The link to be added to the world storage.
          required: true
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorldLink'
      responses:
        '200':
          description: OK, return the UUID of the World Link defined by the world storage.
          content:
            text/plain:
              schema: 
                type: string
                example: "777266da-e286-11ec-8fea-0242ac120002"            
        '201':
          description: Null response.
          content:
            text/plain:
              schema:
                type: string
                example: ""
        '400':
          $ref: '#/components/responses/400_BadRequest'
        '409': 
          $ref: '#/components/responses/409_NotEmptyUUID'
        'default':
          $ref: '#/components/responses/4xx_UnexpectedError'
    put:
      summary: Modify a World Link.
      operationId: modifyWorldLink
      description: Modify an existing World Link given a json object containing all the required informations. <br> **Please note that ID of the object is required in the JSON**
      tags:
        - World Links
      requestBody:
          description: The World Link to be modified in the world storage.
          required: true
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorldLink'
      responses:
        '200':
          description: OK, return the UUID of the modified World Link.
          content:
            text/plain:
              schema:
                type: string
                example: "777266da-e286-11ec-8fea-0242ac120002"
        '400':
          $ref: '#/components/responses/400_BadRequest'
        '404': 
          $ref: '#/components/responses/404_NotFoundUUID'
        'default':
          $ref: '#/components/responses/4xx_UnexpectedError'
    get:
      summary: Return all World Links.
      description: Get all the World Links currently being stored in the world storage.
      operationId: getWorldLinks
      tags:
        - World Links
      responses:
        '200':
          description: OK return all the World Links defined by the world storage.
          content:
            application/json:
              schema:
                type : array
                items :
                  $ref: "#/components/schemas/WorldLink"          
        '201':
          description: Null response.
          content:
            text/plain:
              schema:
                type: string
                example: ""
        default:
         $ref: '#/components/responses/4xx_UnexpectedError'

  /worldLinks/{worldLinkUUID}:
    get:
      summary: Find a World Link by its UUID.
      operationId: getWorldLinkById
      description: Get a single World Link stored in the world storage from its ID.
      tags:
      - World Links
      parameters:
        - name: worldLinkUUID
          in: path
          description: UUID of the World Link to retrieve.
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Successful operation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorldLink' 
        '400':
          $ref: '#/components/responses/400_InvalidUUID'
        '404':
          $ref: '#/components/responses/404_NotFoundUUID'
    delete:
      summary: Delete a World Link.
      operationId: deleteWorldLink
      description: Delete a single World Link stored in the world storage from its ID.
      tags:
      - World Links
      parameters:
        - name: worldLinkUUID
          in: path
          description: World Link id to delete.
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: OK, delete successful.
          content:
            text/plain:
              schema:
                type: string
                example: "Element succesfully deleted"
        '400':
          $ref: '#/components/responses/400_InvalidUUID'
        '404':
         $ref: '#/components/responses/404_NotFoundUUID'
 
# COMPONENTS ###############################################
components:

  #-------------------------------
  # Reusable schemas (data models)
  #-------------------------------
  schemas:
    Trackable:
      description: An element representing a Trackable object in the real world.
      type: object
      required:
        - name
        - creatorUUID
        - trackableType
        - trackableEncodingInformation
        - trackablePayload
        - localCRS
        - unit
        - trackableSize
        - keyvalueTags
      properties:
        UUID:
          description: An Universally Unique IDentifier identifying the Trackable (RFC 4122).
          type: string
          format: uuid
          example: fa8bbe40-8052-11ec-a8a3-0242ac120002
        name:
          description: A human readable name for the Trackable.
          type: string
          example: myTrackableXYZ
        creatorUUID:        
          description: An Universally Unique IDentifier identifying the creator of the Trackable (a person, a team or a company).
          type: string
          format: uuid
          example: bd6ce7ce-7fe8-487d-a179-fddfe914f293
        trackableType:
          description: Extensible list of Trackable types, possibly handled by complient world storage implementation.
          type: string
          enum: [FIDUCIAL_MARKER, IMAGE_MARKER, MAP, GEOPOSE, 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:
      description: An element describing a pose in the world graph.
      type: object
      required:
        - name
        - creatorUUID        
        - localCRS
        - unit
        - worldAnchorSize
        - keyvalueTags
      properties:
        UUID:
          description: An Universally Unique IDentifier identifying the World Anchor (RFC 4122).
          type: string
          format: uuid
          example: 49d18ab3-1bf8-481d-919b-cd062a2fd428
        name:
          description: A human readable name for the World Anchor.
          type: string
          example: myWorldAnchorXYZ
        creatorUUID:
          description: An Universally Unique IDentifier identifying the creator of the World Anchor.
          type: string
          format: uuid
          example: 6ddeb59e-7740-42f7-b329-1374b92e7fc2
        localCRS:
          $ref: '#/components/schemas/Transform3D'
        unit:
          $ref: '#/components/schemas/UnitSystem'
        worldAnchorSize:
          $ref: '#/components/schemas/Size'
        keyvalueTags:
          $ref: '#/components/schemas/KeyvalueTagList'

    WorldLink:
      description: An object holding the info of a transform between two elements.
      type: object
      required:
        - creatorUUID
        - UUIDFrom
        - UUIDTo
        - typeFrom
        - typeTo
        - transform
        - unit
        - keyvalueTags
      properties:
        UUID:
          description: An Universally Unique IDentifier identifying the World Link (RFC 4122).
          type: string
          format: uuid
          example: c6998f4f-1b8d-460b-9de8-4793b92fae2a
        creatorUUID:
          description: An Universally Unique IDentifier identifying the creator of the World Link.
          type: string
          format: uuid
          example: 7506001c-9c00-4f84-ae2e-e4dfcb77d36a
        UUIDFrom:
          description: An Universally Unique IDentifier identifying a World Anchor or Trackable.
          type: string
          format: uuid
          example: 60e11d81-1230-4588-be4c-93520a275012
        UUIDTo:
          description: An Universally Unique IDentifier identifying a World Anchor or Trackable.
          type: string
          format: uuid
          example: 85eed503-875c-4d3d-9569-06c4859bd4cd
        typeFrom:
          $ref: '#/components/schemas/ObjectType'
        typeTo:
          $ref: '#/components/schemas/ObjectType'
        transform:
          $ref: '#/components/schemas/Transform3D'
        unit:
          $ref: '#/components/schemas/UnitSystem'
        keyvalueTags:
          $ref: '#/components/schemas/KeyvalueTagList'

    EncodingInformationStructure:
      description: An object holding the info of a Trackable`'`s encoding informations `:` the data format and the version.
      required:
        - dataFormat
        - version
      properties:
        dataFormat:
          description: Identifier of the target framework.
          type: string
          enum: [HOLOLENS, ARKIT, ARCORE, VUFORIA, ARUCO, OTHER]
          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: [ 1, 0, 0, 3,
                   0, 1, 0, 3,
                   0, 0, 1, 3,
                   0, 0, 0, 1]

    ObjectType:
        description: Type of a world representaion object.
        type: string
        enum: [Trackable, WorldAnchor, NotIdentified]
        example: Trackable

    UnitSystem:
        description: Unit of length.
        type: string
        enum: [MM,  CM,  DM,  M,  DAM,  HM,  KM,  INCH, FOOT, YARD, MILE]
        example: M

    Size:
        description: Size object in format {width, length, depth}.
        type: array
        items:
            type: number
            format: double
        minItems: 3
        maxItems: 3
        example: [1.0,1.0,1.5]   

    KeyvalueTagList:   
        description: List of additional parameters to be stored with the object.
        type: object
        additionalProperties:
            type: array
            items:
                type: string
            minItems: 1
        example: { "Place" : ["Building 123"], "Room" : ["007"]} 

    Error:
      required:
        - code
        - message
      properties:
        code:
          type: integer
          format: int32
          example: 406
        message:
          type: string
          example: "Error 406"
          
  #-------------------------------
  # Reusable responses
  #-------------------------------
  responses:
    #######################
    # 1xx : Informational #
    #######################

    #################
    # 2xx : Success #
    #################

    #####################
    # 3xx : Redirection #
    #####################

    #######################
    # 4xx : Client Errors #
    #######################
    400_BadRequest:
      description: Bad request.
      content:
        text/plain:
          schema:
            type: string
            example: "Bad request"

    400_InvalidUUID:
      description: Invalid UUID supplied.
      content:
        text/plain:
          schema:
            example: "The format of the UUID is incorrect"
            type: string

    404_NotFoundUUID:
      description: Not found, could not find UUID in database.
      content:
        text/plain:
          schema:
            type: string
            example: "Element not found"

    409_NotEmptyUUID:
      description: Invalid UUID, id must be a Nil value.
      content:
        text/plain:
          schema:
            type: string
            example: "The element you sent has already a value and can't be sent to the world storage"

    4xx_UnexpectedError:      # Can be referenced as '#/components/responses/GenericError'
      description: Unexpected error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

    ########################
    # 5xx : Server Errors  #
    ########################
    5xx_UnexpectedError:
      description: Unexpected server error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'