openapi.yaml

openapi: "3.0.0"
info: 
  version: 0.0.2
  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'
    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
    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"              
components:
  schemas:
    trackable:
      type: object
      required:
        - creatorUID
        - trackableType
        - trackableEncodingInformation
        - trackablePayload
        - unitSystem
        - trackableDimension
        - keyvalueTagList
      properties:
        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 of the trackable
          type: array
          minItems: 4
          maxItems: 4
          items:
            type: array
            items: 
              type: number
              format: float
            minItems: 4
            maxItems: 4
          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
        trackableDimension:
          description: Bounding box of the Trackable, {width, length, 0} for 2D trackables, {width, length, depth} for 3D trackables
          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: { "author" : ["james","donovan"], "image" : ["skater"]}
    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"
    Error:
      required:
        - code
        - message
      properties:
        code:
          type: integer
          format: int32
        message:
          type: string