format: refactor spec to add doc (d3466c43) · Commits · ARF - Augmented Reality Framework / ARF005

API/openapi.yaml

+83 −96

Original line number	Diff line number	Diff line
		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. <br>Trackables are elements of the real world of which features are available and/or could be extracted.<br> 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. <br>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:
		@@ -39,10 +50,6 @@ paths:
		responses:
		'200':
		description: OK, world storage server ready.
		content:
		text/plain:
		schema:
		type: string
		/version:
		get:
		summary: Get the version of the ARF API.
		@@ -50,33 +57,27 @@ paths:
		responses:
		'200':
		description: Current version.
		content:
		text/plain:
		schema:
		type: string

		##############
		# 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. <br>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. <br>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'
		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. <br>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
		#-------------------------------