From d3466c43668f8b4ca3b99121caab7a2cac47b0ef Mon Sep 17 00:00:00 2001 From: Nathan Chambron Date: Tue, 31 May 2022 10:44:10 +0200 Subject: [PATCH 1/4] format: refactor spec to add doc --- API/openapi.yaml | 179 ++++++++++++++++++++++------------------------- 1 file changed, 83 insertions(+), 96 deletions(-) diff --git a/API/openapi.yaml b/API/openapi.yaml index d8ea76e..4d6b7de 100644 --- a/API/openapi.yaml +++ b/API/openapi.yaml @@ -1,9 +1,7 @@ -openapi: "3.0.0" -# +# 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) -# (C) ETSI - 2022 # # References: # - Explaination UUID: https://en.wikipedia.org/wiki/Universally_unique_identifier / https://fr.wikipedia.org/wiki/Universally_unique_identifier @@ -14,16 +12,29 @@ openapi: "3.0.0" # - Guide: https://restfulapi.net/http-status-codes/ # # Last Version: 17.05.2022 -# + +openapi: "3.0.0" + info: version: 0.0.6 title: World Storage API description: API ensuring interoperability between an authoring tool and a World Storage service license: - name: BSD-3-clause + 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.
Trackables are elements of the real world of which features are available and/or could be extracted.
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.
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: @@ -38,45 +49,35 @@ paths: operationId: getAdmin responses: '200': - description: OK, world storage server ready. - content: - text/plain: - schema: - type: string + description: OK, world storage server ready. /version: get: summary: Get the version of the ARF API. operationId: getVersion responses: '200': - description: Current version. - content: - text/plain: - schema: - type: string + description: Current version. ############## # TRACKABLES # ############## /trackables: post: - summary: Create a trackable. + 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.
As a result you will get the ID of the newly created Trackable. tags: - - trackables + - Trackables requestBody: - description: The trackable to be added to the world storage. + 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. + description: OK, return the UUID of the Trackable defined by the world storage. content: text/plain: schema: @@ -90,13 +91,14 @@ paths: 'default': $ref: '#/components/responses/4xx_UnexpectedError' get: - summary: Returns the list of all trackables defined by the world storage. + summary: Return all the Trackables. operationId: getTrackables + description: Get all the Trackables currently being stored in the world storage. tags: - - trackables + - Trackables responses: '200': - description: OK, returns all the Trackables defined by the world storage. + description: OK, return all the Trackables defined by the world storage. content: application/json: schema: @@ -112,12 +114,13 @@ paths: 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 + - Trackables parameters: - name: trackableUUID in: path - description: UUID of the trackable to retrieve. + description: UUID of the Trackable to retrieve. required: true schema: type: string @@ -134,10 +137,11 @@ paths: '404': $ref: '#/components/responses/404_NotFoundUUID' delete: - summary: Deletes a trackable. + summary: Delete a Trackable. operationId: deleteTrackable + description: Delete a single Trackable stored in the world storage from its ID. tags: - - trackables + - Trackables parameters: - name: trackableUUID in: path @@ -159,23 +163,21 @@ paths: ################# /worldAnchors: post: - summary: Create a world anchor. + 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.
As a result you will get the ID of the newly created World Anchor. tags: - - world anchors + - World Anchors requestBody: - description: The world anchor to be added to the world storage. + 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' + $ref: '#/components/schemas/WorldAnchor' responses: '200': - description: OK, returns the UUID of the World Anchor defined by the world storage. + description: OK, return the UUID of the World Anchor defined by the world storage. content: text/plain: schema: @@ -189,13 +191,14 @@ paths: 'default': $ref: '#/components/responses/4xx_UnexpectedError' get: - summary: Returns the list of all world anchors defined by the world storage. + summary: Return all the World Anchors. operationId: getWorldAnchors + description: Get all the World Anchors currently being stored in the world storage. tags: - - world anchors + - World Anchors responses: '200': - description: OK, returns all the world anchors defined by the world storage. + description: OK, return all the World Anchors defined by the world storage. content: application/json: schema: @@ -209,14 +212,15 @@ paths: /worldAnchors/{worldAnchorUUID}: get: - summary: Find a world anchor by its UUID. + 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 + - World Anchors parameters: - name: worldAnchorUUID in: path - description: UUID of the world anchor to retrieve. + description: UUID of the World Anchor to retrieve. required: true schema: type: string @@ -233,14 +237,15 @@ paths: '404': $ref: '#/components/responses/404_NotFoundUUID' delete: - summary: Deletes a world anchor. + summary: Delete a World Anchor. operationId: deleteWorldAnchor + description: Delete a single World Anchor stored in the world storage from its ID. tags: - - world anchors + - World Anchors parameters: - name: worldAnchorUUID in: path - description: World anchor UUID to delete. + description: World Anchor UUID to delete. required: true schema: type: string @@ -258,10 +263,11 @@ paths: ############### /worldLinks: post: - summary: Create a link between world anchors and trackables. + 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.
As a result you will get the ID of the newly created World Link. tags: - - world links + - World Links requestBody: description: The link to be added to the world storage. required: true @@ -269,12 +275,9 @@ paths: 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. + description: OK, return the UUID of the World Link defined by the world storage. content: text/plain: schema: @@ -288,13 +291,14 @@ paths: 'default': $ref: '#/components/responses/4xx_UnexpectedError' get: - summary: Returns the list of all links defined by the world storage. + summary: Return all World Links. + description: Get all the World Links currently being stored in the world storage. operationId: getWorldLinks tags: - - world links + - World Links responses: '200': - description: OK returns all the worldLinks defined by the world storage. + description: OK return all the World Links defined by the world storage. content: application/json: schema: @@ -308,14 +312,15 @@ paths: /worldLinks/{worldLinkUUID}: get: - summary: Find a link by its UUID. + 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 + - World Links parameters: - name: worldLinkUUID in: path - description: UUID of the link to retrieve. + description: UUID of the World Link to retrieve. required: true schema: type: string @@ -332,14 +337,15 @@ paths: '404': $ref: '#/components/responses/404_NotFoundUUID' delete: - summary: Deletes a worldLink. + summary: Delete a World Link. operationId: deleteWorldLink + description: Delete a single World Link stored in the world storage from its ID. tags: - - world links + - World Links parameters: - name: worldLinkUUID in: path - description: link id to delete + description: World Link id to delete. required: true schema: type: string @@ -354,26 +360,13 @@ paths: # COMPONENTS ############################################### components: - #------------------------------- - # Reusable operation parameters - #------------------------------- - parameters: - UUIDParams: - name: UUID - in: path - required: true - description: An Universally Unique IDentifier identifying the object (RFC 4122). - schema: - type: string - format: uuid - default: "00000000-0000-0000-0000-000000000000" #------------------------------- # Reusable schemas (data models) #------------------------------- schemas: Trackable: - description: An element representing a trackable object in the real world. + description: An element representing a Trackable object in the real world. type: object required: - name @@ -387,28 +380,28 @@ components: - keyvalueTags properties: UUID: - description: An 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. + 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). + 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. + 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. + description: The data provided to create the Trackable in a specific format handled by the world storage service. type: string format: byte example: "10110101" @@ -419,9 +412,7 @@ 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. @@ -435,16 +426,16 @@ components: - keyvalueTags properties: UUID: - description: An 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: 49d18ab3-1bf8-481d-919b-cd062a2fd428 name: - description: A human readable name for the world anchor. + 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. + description: An Universally Unique IDentifier identifying the creator of the World Anchor. type: string format: uuid example: 6ddeb59e-7740-42f7-b329-1374b92e7fc2 @@ -455,9 +446,7 @@ 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. @@ -472,22 +461,22 @@ components: - keyvalueTags properties: UUID: - description: An Universally Unique IDentifier identifying the link (RFC 4122). + 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 link. + 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. + 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. + description: An Universally Unique IDentifier identifying a World Anchor or Trackable. type: string format: uuid example: 85eed503-875c-4d3d-9569-06c4859bd4cd @@ -499,14 +488,11 @@ components: $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"]} EncodingInformationStructure: + description: An object holding the info of a Trackable`'`s encoding informations `:` the data format and the version. required: - dataFormat - version @@ -547,7 +533,7 @@ components: example: M Size: - description: Size {width, length, depth}. + description: Size object in format {width, length, depth}. type: array items: type: number @@ -576,6 +562,7 @@ components: format: int32 message: type: string + #------------------------------- # Reusable responses #------------------------------- -- GitLab From b57c44eb07bdce4fa153eeec759e7141d63a35c7 Mon Sep 17 00:00:00 2001 From: Nathan Chambron Date: Tue, 31 May 2022 11:03:01 +0200 Subject: [PATCH 2/4] feat: add put endpoints for Trackable, World Anchors and Wolrd Links --- API/openapi.yaml | 80 +++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 69 insertions(+), 11 deletions(-) diff --git a/API/openapi.yaml b/API/openapi.yaml index 4d6b7de..4f710f9 100644 --- a/API/openapi.yaml +++ b/API/openapi.yaml @@ -77,11 +77,7 @@ paths: $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 + description: OK, return the UUID of the Trackable defined by the world storage. '201': description: Null response. '400': @@ -90,6 +86,28 @@ paths: $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.
**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. + '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 @@ -112,7 +130,7 @@ paths: /trackables/{trackableUUID}: get: - summary: Find a trackable by its UUID. + summary: Find a Trackable by its UUID. operationId: getTrackableById description: Get a single Trackable stored in the world storage from its ID. tags: @@ -177,11 +195,7 @@ paths: $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 + description: OK, return the UUID of the World Anchor defined by the world storage. '201': description: Null response. '400': @@ -190,6 +204,28 @@ paths: $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.
**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. + '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 @@ -290,6 +326,28 @@ paths: $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.
**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. + '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. -- GitLab From 9bd7860fecdf74dc387229c5092f60886c3a0d51 Mon Sep 17 00:00:00 2001 From: Nathan Chambron Date: Tue, 31 May 2022 11:52:10 +0200 Subject: [PATCH 3/4] fix: chanegd version number to 1.0.0 --- API/openapi.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/API/openapi.yaml b/API/openapi.yaml index 4f710f9..5bbc3fa 100644 --- a/API/openapi.yaml +++ b/API/openapi.yaml @@ -16,7 +16,7 @@ openapi: "3.0.0" info: - version: 0.0.6 + version: 1.0.0 title: World Storage API description: API ensuring interoperability between an authoring tool and a World Storage service license: -- GitLab From 9eb75fcc39cf74c0621b3d54abf628a1b2a953ee Mon Sep 17 00:00:00 2001 From: Sylvain Renault Date: Wed, 1 Jun 2022 10:13:38 +0000 Subject: [PATCH 4/4] Update openapi.yaml --- API/openapi.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/API/openapi.yaml b/API/openapi.yaml index 5bbc3fa..c601689 100644 --- a/API/openapi.yaml +++ b/API/openapi.yaml @@ -11,7 +11,7 @@ # - Rules for RESTful error code RFC2616: https://datatracker.ietf.org/doc/html/rfc2616#section-10 # - Guide: https://restfulapi.net/http-status-codes/ # -# Last Version: 17.05.2022 +# Last Version: 01.06.2022 openapi: "3.0.0" -- GitLab