diff --git a/API/openapi.yaml b/API/openapi.yaml index eef5f941aa2c699f551142cafd29de614d1ec260..d8ea76e730ef106c6083232f19d4b701435ebd13 100644 --- a/API/openapi.yaml +++ b/API/openapi.yaml @@ -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.4 + version: 0.0.6 title: World Storage API description: API ensuring interoperability between an authoring tool and a World Storage service license: @@ -33,11 +34,22 @@ paths: description: OK, world storage alive. /admin: get: - summary: Get the version of the API. + summary: Get the state of the server. + operationId: getAdmin + responses: + '200': + description: OK, world storage server ready. + content: + text/plain: + schema: + type: string + /version: + get: + summary: Get the version of the ARF API. operationId: getVersion responses: '200': - description: OK, world storage ready. + description: Current version. content: text/plain: schema: @@ -340,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: #------------------------------- @@ -376,7 +362,7 @@ components: name: UUID in: path required: true - description: A Universally Unique IDentifier identifying the object + description: An Universally Unique IDentifier identifying the object (RFC 4122). schema: type: string format: uuid @@ -387,8 +373,10 @@ components: #------------------------------- schemas: Trackable: + description: An element representing a trackable object in the real world. type: object required: + - name - creatorUUID - trackableType - trackableEncodingInformation @@ -399,19 +387,23 @@ 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 + name: + description: A human readable name for the trackable. + 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, GEOPOSE, OTHER] example: FIDUCIAL_MARKER trackableEncodingInformation: $ref: '#/components/schemas/EncodingInformationStructure' @@ -421,17 +413,21 @@ components: format: byte example: "10110101" localCRS: - $ref: '#/components/schemas/Transform3D' + $ref: '#/components/schemas/Transform3D' unit: - $ref: '#/components/schemas/UnitSystem' + $ref: '#/components/schemas/UnitSystem' trackableSize: - $ref: '#/components/schemas/Size' + $ref: '#/components/schemas/Size' keyvalueTags: - $ref: '#/components/schemas/KeyvalueTagList' + 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 - creatorUUID - localCRS - unit @@ -439,25 +435,32 @@ 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' + $ref: '#/components/schemas/Transform3D' unit: - $ref: '#/components/schemas/UnitSystem' + $ref: '#/components/schemas/UnitSystem' worldAnchorSize: - $ref: '#/components/schemas/Size' + $ref: '#/components/schemas/Size' keyvalueTags: - $ref: '#/components/schemas/KeyvalueTagList' + 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 @@ -469,64 +472,39 @@ 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' + $ref: '#/components/schemas/Transform3D' unit: - $ref: '#/components/schemas/UnitSystem' + $ref: '#/components/schemas/UnitSystem' linkSize: - $ref: '#/components/schemas/Size' + $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' + description: List of additional parameters to be stored. + $ref: '#/components/schemas/KeyvalueTagList' + example: { "LinkType" : ["Hierarchy"]} EncodingInformationStructure: required: @@ -534,9 +512,9 @@ components: - version properties: dataFormat: - description: Identifier of the target framework + description: Identifier of the target framework. type: string - enum: [HOLOLENS, ARKIT, ARCORE] + enum: [HOLOLENS, ARKIT, ARCORE, VUFORIA, ARUCO, OTHER] example : "HOLOLENS" version: description: The version of the format @@ -544,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] + 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 an world representaion object. + description: Type of a world representaion object. type: string - enum: [Trackable, WorldAnchor, WorldLink] + enum: [Trackable, WorldAnchor, NotIdentified] example: Trackable UnitSystem: @@ -576,17 +554,17 @@ 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 trackable. + description: List of additional parameters to be stored with the object. type: object additionalProperties: type: array items: type: string minItems: 1 - example: { "Place" : ["Museum 1"], "room" : ["B4"]} + example: { "Place" : ["Building 123"], "Room" : ["007"]} Error: required: diff --git a/README.md b/README.md index 101233956c983e1b03ed6da264ffaabddef85522..6c0c54f5605a3f75d980948916266f365c48854c 100644 --- a/README.md +++ b/README.md @@ -13,7 +13,7 @@ # Objectives -Project dedicated to the development of an API standardizing the exchanges with a World Storage Representation service. +This repository is dedicated to the development of the augmented reality framework (ARF) API (ETSI-ISG) for standardizing the exchanges with a World Storage. service. The API contains all the accees actions (REST) data (elements) needed to implement a World Representation with a World Graph. # Associated workspaces