Commit f5d83e40 authored by Sylvain Renault's avatar Sylvain Renault
Browse files

New draft version 

- deleted AttachedObjects (action + schema)
- new version number
- some new descriptions
- new default matrix
- new default UUID (all are now differents)
parent c8802a3a

API/openapi.yaml

+41 −84
Original line number Diff line number Diff line
@@ -9,13 +9,14 @@ openapi: "3.0.0" 
# - 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: 04.03.2022

# Last Version: 17.05.2022

#

info: 

  version: 0.0.5

  version: 0.0.6

  title: World Storage API

  description: API ensuring interoperability between an authoring tool and a World Storage service

  license:
@@ -351,32 +352,6 @@ paths: 
        '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:

  #-------------------------------
@@ -387,7 +362,7 @@ components: 
      name: UUID

      in: path

      required: true

      description: A Universally Unique IDentifier identifying the object (RFC 4122).

      description: An Universally Unique IDentifier identifying the object (RFC 4122).

      schema:

        type: string

        format: uuid
@@ -398,6 +373,7 @@ components: 
  #-------------------------------

  schemas:

    Trackable:

      description: An element representing a trackable object in the real world.

      type: object

      required:

        - name
@@ -411,7 +387,7 @@ components: 
        - keyvalueTags

      properties:

        UUID:

          description: A Universally Unique IDentifier identifying the trackable (RFC 4122).

          description: An Universally Unique IDentifier identifying the trackable (RFC 4122).

          type: string

          format: uuid

          example: fa8bbe40-8052-11ec-a8a3-0242ac120002
@@ -420,14 +396,14 @@ components: 
          type: string

          example: myTrackableXYZ

        creatorUUID:        

          description: A Universally Unique IDentifier identifying the creator of the trackable (a person, a team or a company).

          description: An 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

          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, OTHER]

          enum: [FIDUCIAL_MARKER, IMAGE_MARKER, MAP, GEOPOSITION, OTHER]

          example: FIDUCIAL_MARKER

        trackableEncodingInformation:         

          $ref: '#/components/schemas/EncodingInformationStructure'
@@ -443,9 +419,12 @@ components: 
        trackableSize:

          $ref: '#/components/schemas/Size'

        keyvalueTags:

          description: List of additional parameters to be stored.

          $ref: '#/components/schemas/KeyvalueTagList'

          example: { "TrackableType" : ["Standard"]}   



    WorldAnchor:

      description: An element describing a pose in the world graph.

      type: object

      required:

        - name
@@ -456,19 +435,19 @@ components: 
        - keyvalueTags

      properties:

        UUID:

          description: A Universally Unique IDentifier identifying the world anchor (RFC 4122).

          description: An Universally Unique IDentifier identifying the world anchor (RFC 4122).

          type: string

          format: uuid

          example: ce8ccd80-56ee-2a5c-a8a3-0242ac150d002

          example: 49d18ab3-1bf8-481d-919b-cd062a2fd428

        name:

          description: A human readable name for the world anchor.

          type: string

          example: myWorldAnchorXYZ

        creatorUUID:

          description: A Universally Unique IDentifier identifying the creator of the world anchor.

          description: An Universally Unique IDentifier identifying the creator of the world anchor.

          type: string

          format: uuid

          example: c75f6324-77a0-11ec-90d6-0242ac120003

          example: 6ddeb59e-7740-42f7-b329-1374b92e7fc2

        localCRS:

          $ref: '#/components/schemas/Transform3D'

        unit:
@@ -476,9 +455,12 @@ components: 
        worldAnchorSize:

          $ref: '#/components/schemas/Size'

        keyvalueTags:

          description: List of additional parameters to be stored.

          $ref: '#/components/schemas/KeyvalueTagList'

          example: { "AnchorType" : ["Static"]}   



    WorldLink:

      description: An object holding the info of a transform between two elements.

      type: object

      required:

        - creatorUUID
@@ -490,25 +472,29 @@ components: 
        - keyvalueTags

      properties:

        UUID:

          description: A Universally Unique IDentifier identifying the link (RFC 4122).

          description: An Universally Unique IDentifier identifying the link (RFC 4122).

          type: string

          format: uuid

          example: ce8ccd80-56ee-2a5c-a8a3-0242ac150d002

          example: c6998f4f-1b8d-460b-9de8-4793b92fae2a

        creatorUUID:

          description: A Universally Unique IDentifier identifying the creator of the link.

          description: An Universally Unique IDentifier identifying the creator of the link.

          type: string

          format: uuid

          example: c75f6324-77a0-11ec-90d6-0242ac120003

          example: 7506001c-9c00-4f84-ae2e-e4dfcb77d36a

        UUIDFrom:

          description: A Universally Unique IDentifier identifying a world anchor or trackable.

          description: An Universally Unique IDentifier identifying a world anchor or trackable.

          type: string

          format: uuid

          example: ce8ccd80-56ee-2a5c-a8a3-0242ac150d002

          example: 60e11d81-1230-4588-be4c-93520a275012

        UUIDTo:

          description: A Universally Unique IDentifier identifying a world anchor or trackable.

          description: An Universally Unique IDentifier identifying a world anchor or trackable.

          type: string

          format: uuid

          example: ce8ccd80-56ee-2a5c-a8a3-0242ac150d002    

          example: 85eed503-875c-4d3d-9569-06c4859bd4cd

        typeFrom:

          $ref: '#/components/schemas/ObjectType'

        typeTo:

          $ref: '#/components/schemas/ObjectType'

        transform:

          $ref: '#/components/schemas/Transform3D'

        unit:
@@ -520,42 +506,13 @@ components: 
          $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

          description: Identifier of the target framework.

          type: string

          enum: [HOLOLENS, ARKIT, ARCORE, VUFORIA, ARUCO, OTHER]

          example : "HOLOLENS"
@@ -565,22 +522,22 @@ components: 
          example : "1.01"



    Transform3D:

        description: Coordinate reference system of the world anchor, a 4*4 matrix (rowmajor) represented by a float vector

        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]

        example: [ 1, 0, 0, 3,

                   0, 1, 0, 3,

                   0, 0, 1, 3,

                   0, 0, 0, 1]



    ObjectType:

        description: Type of an world representaion object.

        description: Type of a world representaion object.

        type: string

        enum: [Trackable, WorldAnchor, WorldLink, NotIdentified]

        enum: [Trackable, WorldAnchor, NotIdentified]

        example: Trackable



    UnitSystem:
@@ -597,7 +554,7 @@ components: 
            format: double

        minItems: 3

        maxItems: 3

        example: [1,5,0]   

        example: [1.0,1.0,1.5]   



    KeyvalueTagList:   

        description: List of additional parameters to be stored with the object.
@@ -607,7 +564,7 @@ components: 
            items:

                type: string

            minItems: 1

        example: { "Place" : ["Museum 1"], "room" : ["B4"]} 

        example: { "Place" : ["Building 123"], "Room" : ["007"]} 



    Error:

      required: