diff --git a/API/openapi.yaml b/API/openapi.yaml index d8ea76e730ef106c6083232f19d4b701435ebd13..c601689fc10c80efaeb373f3f3f5ffc1ec69eb17 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 @@ -13,17 +11,30 @@ openapi: "3.0.0" # - 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" + 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: - 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,49 +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. - content: - text/plain: - schema: - type: string + description: OK, return the UUID of the Trackable defined by the world storage. '201': description: Null response. '400': @@ -89,14 +86,37 @@ 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: 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: @@ -110,14 +130,15 @@ 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: - - 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 +155,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,27 +181,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. - 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': @@ -188,14 +204,37 @@ 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: 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 +248,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 +273,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 +299,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 +311,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: @@ -287,14 +326,37 @@ 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: 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 +370,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 +395,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 +418,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 +438,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 +470,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 +484,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 +504,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 +519,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 +546,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 +591,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 +620,7 @@ components: format: int32 message: type: string + #------------------------------- # Reusable responses #-------------------------------