Merge branch 'feature/FormatSpec' into 'develop' (4cc311cc) · Commits · ARF - Augmented Reality Framework / ARF005

API/openapi.yaml

+152 −107

Original line number	Original line	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)		# API for the Augmented Reality Framework (ARF)
	# Working group: ETSI ISG ARF		# Working group: ETSI ISG ARF
	# STF group: STF620 (validation)		# STF group: STF620 (validation)
	# (C) ETSI - 2022
	#		#
	# References:		# References:
	# - Explaination UUID: https://en.wikipedia.org/wiki/Universally_unique_identifier / https://fr.wikipedia.org/wiki/Universally_unique_identifier		# - 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		# - Rules for RESTful error code RFC2616: https://datatracker.ietf.org/doc/html/rfc2616#section-10
	# - Guide: https://restfulapi.net/http-status-codes/		# - Guide: https://restfulapi.net/http-status-codes/
	#		#
	# Last Version: 17.05.2022		# Last Version: 01.06.2022
	#
			openapi: "3.0.0"

	info:		info:
	version: 0.0.6		version: 1.0.0
	title: World Storage API		title: World Storage API
	description: API ensuring interoperability between an authoring tool and a World Storage service		description: API ensuring interoperability between an authoring tool and a World Storage service
	license:		license:
	name: BSD-3-clause		name: Copyright 2022 ETSI. Licensed under the BSD-3-Clause license
	url: https://opensource.org/licenses/BSD-3-Clause		url: https://opensource.org/licenses/BSD-3-Clause
	servers:		servers:
	- url: http://localhost:8080		- 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:		paths:
	/ping:		/ping:
	get:		get:
	@@ -39,10 +50,6 @@ paths:
	responses:		responses:
	'200':		'200':
	description: OK, world storage server ready.		description: OK, world storage server ready.
	content:
	text/plain:
	schema:
	type: string
	/version:		/version:
	get:		get:
	summary: Get the version of the ARF API.		summary: Get the version of the ARF API.
	@@ -50,37 +57,27 @@ paths:
	responses:		responses:
	'200':		'200':
	description: Current version.		description: Current version.
	content:
	text/plain:
	schema:
	type: string

	##############		##############
	# TRACKABLES #		# TRACKABLES #
	##############		##############
	/trackables:		/trackables:
	post:		post:
	summary: Create a trackable.		summary: Create a Trackable.
	operationId: addTrackable		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:		tags:
	- trackables		- Trackables
	requestBody:		requestBody:
	description: The trackable to be added to the world storage.		description: The Trackable to be added to the world storage.
	required: true		required: true
	content:		content:
	application/json:		application/json:
	schema:		schema:
	$ref: '#/components/schemas/Trackable'		$ref: '#/components/schemas/Trackable'
	#application/xml:
	# schema:
	# $ref: '#/components/schemas/Trackable'
	responses:		responses:
	'200':		'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:
	type: string
	'201':		'201':
	description: Null response.		description: Null response.
	'400':		'400':
	@@ -89,14 +86,37 @@ paths:
	$ref: '#/components/responses/409_NotEmptyUUID'		$ref: '#/components/responses/409_NotEmptyUUID'
	'default':		'default':
	$ref: '#/components/responses/4xx_UnexpectedError'		$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. <br> 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:		get:
	summary: Returns the list of all trackables defined by the world storage.		summary: Return all the Trackables.
	operationId: getTrackables		operationId: getTrackables
			description: Get all the Trackables currently being stored in the world storage.
	tags:		tags:
	- trackables		- Trackables
	responses:		responses:
	'200':		'200':
	description: OK, returns all the Trackables defined by the world storage.		description: OK, return all the Trackables defined by the world storage.
	content:		content:
	application/json:		application/json:
	schema:		schema:
	@@ -110,14 +130,15 @@ paths:

	/trackables/{trackableUUID}:		/trackables/{trackableUUID}:
	get:		get:
	summary: Find a trackable by its UUID.		summary: Find a Trackable by its UUID.
	operationId: getTrackableById		operationId: getTrackableById
			description: Get a single Trackable stored in the world storage from its ID.
	tags:		tags:
	- trackables		- Trackables
	parameters:		parameters:
	- name: trackableUUID		- name: trackableUUID
	in: path		in: path
	description: UUID of the trackable to retrieve.		description: UUID of the Trackable to retrieve.
	required: true		required: true
	schema:		schema:
	type: string		type: string
	@@ -134,10 +155,11 @@ paths:
	'404':		'404':
	$ref: '#/components/responses/404_NotFoundUUID'		$ref: '#/components/responses/404_NotFoundUUID'
	delete:		delete:
	summary: Deletes a trackable.		summary: Delete a Trackable.
	operationId: deleteTrackable		operationId: deleteTrackable
			description: Delete a single Trackable stored in the world storage from its ID.
	tags:		tags:
	- trackables		- Trackables
	parameters:		parameters:
	- name: trackableUUID		- name: trackableUUID
	in: path		in: path
	@@ -159,27 +181,21 @@ paths:
	#################		#################
	/worldAnchors:		/worldAnchors:
	post:		post:
	summary: Create a world anchor.		summary: Create a World Anchor.
	operationId: addWorldAnchor		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:		tags:
	- world anchors		- World Anchors
	requestBody:		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		required: true
	content:		content:
	application/json:		application/json:
	schema:		schema:
	$ref: '#/components/schemas/WorldAnchor'		$ref: '#/components/schemas/WorldAnchor'
	#application/xml:
	# schema:
	# $ref: '#/components/schemas/WorldAnchor'
	responses:		responses:
	'200':		'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:
	type: string
	'201':		'201':
	description: Null response.		description: Null response.
	'400':		'400':
	@@ -188,14 +204,37 @@ paths:
	$ref: '#/components/responses/409_NotEmptyUUID'		$ref: '#/components/responses/409_NotEmptyUUID'
	'default':		'default':
	$ref: '#/components/responses/4xx_UnexpectedError'		$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. <br> 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:		get:
	summary: Returns the list of all world anchors defined by the world storage.		summary: Return all the World Anchors.
	operationId: getWorldAnchors		operationId: getWorldAnchors
			description: Get all the World Anchors currently being stored in the world storage.
	tags:		tags:
	- world anchors		- World Anchors
	responses:		responses:
	'200':		'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:		content:
	application/json:		application/json:
	schema:		schema:
	@@ -209,14 +248,15 @@ paths:

	/worldAnchors/{worldAnchorUUID}:		/worldAnchors/{worldAnchorUUID}:
	get:		get:
	summary: Find a world anchor by its UUID.		summary: Find a World Anchor by its UUID.
	operationId: getWorldAnchorById		operationId: getWorldAnchorById
			description: Get a single World Anchor stored in the world storage from its ID.
	tags:		tags:
	- world anchors		- World Anchors
	parameters:		parameters:
	- name: worldAnchorUUID		- name: worldAnchorUUID
	in: path		in: path
	description: UUID of the world anchor to retrieve.		description: UUID of the World Anchor to retrieve.
	required: true		required: true
	schema:		schema:
	type: string		type: string
	@@ -233,14 +273,15 @@ paths:
	'404':		'404':
	$ref: '#/components/responses/404_NotFoundUUID'		$ref: '#/components/responses/404_NotFoundUUID'
	delete:		delete:
	summary: Deletes a world anchor.		summary: Delete a World Anchor.
	operationId: deleteWorldAnchor		operationId: deleteWorldAnchor
			description: Delete a single World Anchor stored in the world storage from its ID.
	tags:		tags:
	- world anchors		- World Anchors
	parameters:		parameters:
	- name: worldAnchorUUID		- name: worldAnchorUUID
	in: path		in: path
	description: World anchor UUID to delete.		description: World Anchor UUID to delete.
	required: true		required: true
	schema:		schema:
	type: string		type: string
	@@ -258,10 +299,11 @@ paths:
	###############		###############
	/worldLinks:		/worldLinks:
	post:		post:
	summary: Create a link between world anchors and trackables.		summary: Create a World Link between elements (world anchors and/or trackables).
	operationId: addWorldLink		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:		tags:
	- world links		- World Links
	requestBody:		requestBody:
	description: The link to be added to the world storage.		description: The link to be added to the world storage.
	required: true		required: true
	@@ -269,12 +311,9 @@ paths:
	application/json:		application/json:
	schema:		schema:
	$ref: '#/components/schemas/WorldLink'		$ref: '#/components/schemas/WorldLink'
	#application/xml:
	# schema:
	# $ref: '#/components/schemas/WorldLink'
	responses:		responses:
	'200':		'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:		content:
	text/plain:		text/plain:
	schema:		schema:
	@@ -287,14 +326,37 @@ paths:
	$ref: '#/components/responses/409_NotEmptyUUID'		$ref: '#/components/responses/409_NotEmptyUUID'
	'default':		'default':
	$ref: '#/components/responses/4xx_UnexpectedError'		$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. <br> 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:		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		operationId: getWorldLinks
	tags:		tags:
	- world links		- World Links
	responses:		responses:
	'200':		'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:		content:
	application/json:		application/json:
	schema:		schema:
	@@ -308,14 +370,15 @@ paths:

	/worldLinks/{worldLinkUUID}:		/worldLinks/{worldLinkUUID}:
	get:		get:
	summary: Find a link by its UUID.		summary: Find a World Link by its UUID.
	operationId: getWorldLinkById		operationId: getWorldLinkById
			description: Get a single World Link stored in the world storage from its ID.
	tags:		tags:
	- world links		- World Links
	parameters:		parameters:
	- name: worldLinkUUID		- name: worldLinkUUID
	in: path		in: path
	description: UUID of the link to retrieve.		description: UUID of the World Link to retrieve.
	required: true		required: true
	schema:		schema:
	type: string		type: string
	@@ -332,14 +395,15 @@ paths:
	'404':		'404':
	$ref: '#/components/responses/404_NotFoundUUID'		$ref: '#/components/responses/404_NotFoundUUID'
	delete:		delete:
	summary: Deletes a worldLink.		summary: Delete a World Link.
	operationId: deleteWorldLink		operationId: deleteWorldLink
			description: Delete a single World Link stored in the world storage from its ID.
	tags:		tags:
	- world links		- World Links
	parameters:		parameters:
	- name: worldLinkUUID		- name: worldLinkUUID
	in: path		in: path
	description: link id to delete		description: World Link id to delete.
	required: true		required: true
	schema:		schema:
	type: string		type: string
	@@ -354,26 +418,13 @@ paths:

	# COMPONENTS ###############################################		# COMPONENTS ###############################################
	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)		# Reusable schemas (data models)
	#-------------------------------		#-------------------------------
	schemas:		schemas:
	Trackable:		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		type: object
	required:		required:
	- name		- name
	@@ -387,28 +438,28 @@ components:
	- keyvalueTags		- keyvalueTags
	properties:		properties:
	UUID:		UUID:
	description: An Universally Unique IDentifier identifying the trackable (RFC 4122).		description: An Universally Unique IDentifier identifying the Trackable (RFC 4122).
	type: string		type: string
	format: uuid		format: uuid
	example: fa8bbe40-8052-11ec-a8a3-0242ac120002		example: fa8bbe40-8052-11ec-a8a3-0242ac120002
	name:		name:
	description: A human readable name for the trackable.		description: A human readable name for the Trackable.
	type: string		type: string
	example: myTrackableXYZ		example: myTrackableXYZ
	creatorUUID:		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		type: string
	format: uuid		format: uuid
	example: bd6ce7ce-7fe8-487d-a179-fddfe914f293		example: bd6ce7ce-7fe8-487d-a179-fddfe914f293
	trackableType:		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		type: string
	enum: [FIDUCIAL_MARKER, IMAGE_MARKER, MAP, GEOPOSE, OTHER]		enum: [FIDUCIAL_MARKER, IMAGE_MARKER, MAP, GEOPOSE, OTHER]
	example: FIDUCIAL_MARKER		example: FIDUCIAL_MARKER
	trackableEncodingInformation:		trackableEncodingInformation:
	$ref: '#/components/schemas/EncodingInformationStructure'		$ref: '#/components/schemas/EncodingInformationStructure'
	trackablePayload:		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		type: string
	format: byte		format: byte
	example: "10110101"		example: "10110101"
	@@ -419,9 +470,7 @@ components:
	trackableSize:		trackableSize:
	$ref: '#/components/schemas/Size'		$ref: '#/components/schemas/Size'
	keyvalueTags:		keyvalueTags:
	description: List of additional parameters to be stored.
	$ref: '#/components/schemas/KeyvalueTagList'		$ref: '#/components/schemas/KeyvalueTagList'
	example: { "TrackableType" : ["Standard"]}

	WorldAnchor:		WorldAnchor:
	description: An element describing a pose in the world graph.		description: An element describing a pose in the world graph.
	@@ -435,16 +484,16 @@ components:
	- keyvalueTags		- keyvalueTags
	properties:		properties:
	UUID:		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		type: string
	format: uuid		format: uuid
	example: 49d18ab3-1bf8-481d-919b-cd062a2fd428		example: 49d18ab3-1bf8-481d-919b-cd062a2fd428
	name:		name:
	description: A human readable name for the world anchor.		description: A human readable name for the World Anchor.
	type: string		type: string
	example: myWorldAnchorXYZ		example: myWorldAnchorXYZ
	creatorUUID:		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		type: string
	format: uuid		format: uuid
	example: 6ddeb59e-7740-42f7-b329-1374b92e7fc2		example: 6ddeb59e-7740-42f7-b329-1374b92e7fc2
	@@ -455,9 +504,7 @@ components:
	worldAnchorSize:		worldAnchorSize:
	$ref: '#/components/schemas/Size'		$ref: '#/components/schemas/Size'
	keyvalueTags:		keyvalueTags:
	description: List of additional parameters to be stored.
	$ref: '#/components/schemas/KeyvalueTagList'		$ref: '#/components/schemas/KeyvalueTagList'
	example: { "AnchorType" : ["Static"]}

	WorldLink:		WorldLink:
	description: An object holding the info of a transform between two elements.		description: An object holding the info of a transform between two elements.
	@@ -472,22 +519,22 @@ components:
	- keyvalueTags		- keyvalueTags
	properties:		properties:
	UUID:		UUID:
	description: An Universally Unique IDentifier identifying the link (RFC 4122).		description: An Universally Unique IDentifier identifying the World Link (RFC 4122).
	type: string		type: string
	format: uuid		format: uuid
	example: c6998f4f-1b8d-460b-9de8-4793b92fae2a		example: c6998f4f-1b8d-460b-9de8-4793b92fae2a
	creatorUUID:		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		type: string
	format: uuid		format: uuid
	example: 7506001c-9c00-4f84-ae2e-e4dfcb77d36a		example: 7506001c-9c00-4f84-ae2e-e4dfcb77d36a
	UUIDFrom:		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		type: string
	format: uuid		format: uuid
	example: 60e11d81-1230-4588-be4c-93520a275012		example: 60e11d81-1230-4588-be4c-93520a275012
	UUIDTo:		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		type: string
	format: uuid		format: uuid
	example: 85eed503-875c-4d3d-9569-06c4859bd4cd		example: 85eed503-875c-4d3d-9569-06c4859bd4cd
	@@ -499,14 +546,11 @@ components:
	$ref: '#/components/schemas/Transform3D'		$ref: '#/components/schemas/Transform3D'
	unit:		unit:
	$ref: '#/components/schemas/UnitSystem'		$ref: '#/components/schemas/UnitSystem'
	linkSize:
	$ref: '#/components/schemas/Size'
	keyvalueTags:		keyvalueTags:
	description: List of additional parameters to be stored.
	$ref: '#/components/schemas/KeyvalueTagList'		$ref: '#/components/schemas/KeyvalueTagList'
	example: { "LinkType" : ["Hierarchy"]}

	EncodingInformationStructure:		EncodingInformationStructure:
			description: An object holding the info of a Trackable`'`s encoding informations `:` the data format and the version.
	required:		required:
	- dataFormat		- dataFormat
	- version		- version
	@@ -547,7 +591,7 @@ components:
	example: M		example: M

	Size:		Size:
	description: Size {width, length, depth}.		description: Size object in format {width, length, depth}.
	type: array		type: array
	items:		items:
	type: number		type: number
	@@ -576,6 +620,7 @@ components:
	format: int32		format: int32
	message:		message:
	type: string		type: string

	#-------------------------------		#-------------------------------
	# Reusable responses		# Reusable responses
	#-------------------------------		#-------------------------------

Admin message