openapi: "3.0.0"
#
# API for the Augmented Reality Framework (ARF)
# Working group: ETSI ISG ARF
# STF group: STF620 (validation)
# (C) ETSI - 2022
#
# 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
# - Rules for RESTful error code RFC2616: https://datatracker.ietf.org/doc/html/rfc2616#section-10
# - Guide: https://restfulapi.net/http-status-codes/
#
# Last Version: 04.03.2022
#
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
      operationId: getPing
      responses:
        '200':
          description: OK, world storage alive.
  /admin:
    get:
      summary: Get the version of the API.
      operationId: getVersion
      responses:
        '200':
          description: OK, world storage ready.
          content:
            text/plain:
              schema: 
                type: string      

##############
# TRACKABLES #
##############
  /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.
        '400':
          $ref: '#/components/responses/400_BadRequest'
        '409': 
          $ref: '#/components/responses/409_NotEmptyUUID'
        'default':
          $ref: '#/components/responses/4xx_UnexpectedError'
    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:
          $ref: '#/components/responses/4xx_UnexpectedError'

  /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
            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: Deletes a trackable.
      operationId: deleteTrackable
      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.
        '400':
          $ref: '#/components/responses/400_InvalidUUID'
        '404':
          $ref: '#/components/responses/404_NotFoundUUID'   

#################
# WORLD ANCHORS #
#################
  /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.
        '400':
          $ref: '#/components/responses/400_BadRequest'
        '409': 
          $ref: '#/components/responses/409_NotEmptyUUID'
        'default':
          $ref: '#/components/responses/4xx_UnexpectedError'
    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:
          $ref: '#/components/responses/4xx_UnexpectedError'

  /worldAnchors/{worldAnchorUUID}:
    get:
      summary: Find a world anchor by its UUID.
      operationId: getWorldAnchorById
      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: Deletes a world anchor.
      operationId: deleteWorldAnchor
      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.
        '400':
          $ref: '#/components/responses/400_InvalidUUID'
        '404':
          $ref: '#/components/responses/404_NotFoundUUID'   

###############
# WORLD LINKS #
###############
  /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
        '400':
          $ref: '#/components/responses/400_BadRequest'
        '409': 
          $ref: '#/components/responses/409_NotEmptyUUID'
        'default':
          $ref: '#/components/responses/4xx_UnexpectedError'
    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:
         $ref: '#/components/responses/4xx_UnexpectedError'

  /worldLinks/{worldLinkUUID}:
    get:
      summary: Find a link by its UUID.
      operationId: getWorldLinkById
      tags:
      - world links
      parameters:
        - name: worldLinkUUID
          in: path
          description: UUID of the 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: Deletes a worldLink.
      operationId: deleteWorldLink
      tags:
      - world links
      parameters:
        - name: worldLinkUUID
          in: path
          description: link id to delete
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: OK
        '400':
          $ref: '#/components/responses/400_InvalidUUID'
        '404':
         $ref: '#/components/responses/404_NotFoundUUID'
 
  /worldLinks/attached/{worldLinkUUID}:
    get:
      summary: Retrieve end objects connected to this world link by its UUID.
      operationId: getAttachedObjectsFromUUID
      tags:
      - world links
      parameters:
        - name: worldLinkUUID
          in: path
          description: UUID of the link from which you will retrieve the end objects.
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Successful operation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AttachedObjects' 
        '400':
          $ref: '#/components/responses/400_InvalidUUID'
        '404':
          $ref: '#/components/responses/404_NotFoundUUID'

# COMPONENTS ###############################################
components:
  #-------------------------------
  # Reusable operation parameters
  #-------------------------------
  parameters:
    UUIDParams:
      name: UUID
      in: path
      required: true
      description: A Universally Unique IDentifier identifying the object
      schema:
        type: string
        format: uuid
        default: "00000000-0000-0000-0000-000000000000"

  #-------------------------------
  # Reusable schemas (data models)
  #-------------------------------
  schemas:
    Trackable:
      type: object
      required:
        - name
        - creatorUUID
        - trackableType
        - trackableEncodingInformation
        - trackablePayload
        - localCRS
        - unit
        - trackableSize
        - keyvalueTags
      properties:
        UUID:
          description: A 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: newTrackableXYZ
        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:
        - name
        - creatorUUID        
        - localCRS
        - unit
        - worldAnchorSize
        - keyvalueTags
      properties:
        UUID:
          description: A Universally Unique IDentifier identifying the world anchor (RFC 4122).
          type: string
          format: uuid
          example: ce8ccd80-56ee-2a5c-a8a3-0242ac150d002
        name:
          description: A human readable name for the world anchor.
          type: string
          example: newWorldAnchorXYZ
        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 (RFC 4122).
          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"]}    

    AttachedObjects:
      type: object
      required:
        - UUID        
        - UUIDFrom
        - UUIDTo
        - TypeFrom
        - TypeTo
      properties:
        UUID:
          description: A Universally Unique IDentifier identifying the link.
          type: string
          format: uuid
          example: ce8ccd80-56ee-2a5c-a8a3-0242ac150d002
        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   
        TypeFrom:
          $ref: '#/components/schemas/ObjectType'
        TypeTo:
          $ref: '#/components/schemas/ObjectType'

    EncodingInformationStructure:
      required:
        - dataFormat
        - version
      properties:
        dataFormat:
          description: Identifier of the target framework
          type: string
          enum: [HOLOLENS, ARKIT, ARCORE, VUFORIA, ARUCO]
          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]

    ObjectType:
        description: Type of an world representaion object.
        type: string
        enum: [Trackable, WorldAnchor, WorldLink, 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 {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
  #-------------------------------
  # Reusable responses
  #-------------------------------
  responses:
    #######################
    # 1xx : Informational #
    #######################

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

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

    #######################
    # 4xx : Client Errors #
    #######################
    400_BadRequest:
      description: Bad request.

    400_InvalidUUID:
      description: Invalid UUID supplied.

    404_NotFoundUUID:
      description: Not found, could not find UUID in database.

    409_NotEmptyUUID:
      description: Invalid UUID, id must be a Nil value.

    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'