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
#-------------------------------