Major and minor changes. (6d3f113c) · Commits · ARF - Augmented Reality Framework / ARF005

API/openapi.yaml

+258 −105

Original line number	Diff line number	Diff line
		openapi: "3.0.0"
		#
		# 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
		# - UUID formats: 8-4-4-4-12 format string, lower case (but case insensitive on input)
		# - UUID RFC4122: https://datatracker.ietf.org/doc/html/rfc4122#section-3
		# - Rules for RESTful error code RFC2616: https://datatracker.ietf.org/doc/html/rfc2616#section-10
		# - Guide: https://restfulapi.net/http-status-codes/
		#
		info:
		version: 0.0.4
		title: World Storage API
		@@ -14,26 +27,30 @@ paths:
		summary: Test the server availability
		responses:
		'200':
		description: OK
		description: OK, world storage alive.
		/admin:
		get:
		summary: Get the version of the API
		summary: Get the version of the API.
		operationId: getVersion
		responses:
		'200':
		description: OK world storage.
		description: OK, world storage ready.
		content:
		text/plain:
		schema:
		type: string

		##############
		# TRACKABLES #
		##############
		/trackables:
		post:
		summary: Create a trackable
		summary: Create a trackable.
		operationId: addTrackable
		tags:
		- 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:
		@@ -44,30 +61,27 @@ paths:
		$ref: '#/components/schemas/Trackable'
		responses:
		'200':
		description: OK returns the UUID of the Trackable defined by the world storage.
		description: OK, returns the UUID of the Trackable defined by the world storage.
		content:
		text/plain:
		schema:
		type: string
		'201':
		description: Null response
		default:
		description: unexpected error
		content:
		application/json:
		schema:
		$ref: '#/components/schemas/Error'
		# Check 2xx, 4xx, 5xx...
		'401':
		$ref: '#/components/responses/UUID'
		description: Null response.
		'400':
		$ref: '#/components/responses/400_BadRequest'
		'409':
		$ref: '#/components/responses/409_NotEmptyUUID'
		'default':
		$ref: '#/components/responses/4xx_UnexpectedError'
		get:
		summary: returns the list of all trackables defined by the world storage.
		summary: Returns the list of all trackables defined by the world storage.
		operationId: getTrackables
		tags:
		- trackables
		responses:
		'200':
		description: OK returns all the Trackables defined by the world storage.
		description: OK, returns all the Trackables defined by the world storage.
		content:
		application/json:
		schema:
		@@ -75,65 +89,67 @@ paths:
		items :
		$ref: "#/components/schemas/Trackable"
		'201':
		description: Null response
		description: Null response.
		default:
		description: unexpected error
		content:
		application/json:
		schema:
		$ref: "#/components/schemas/Error"
		$ref: '#/components/responses/4xx_UnexpectedError'

		/trackables/{trackableUUID}:
		get:
		summary: Find a trackable by its UUID
		summary: Find a trackable by its UUID.
		operationId: getTrackableById
		tags:
		- 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
		format: uuid
		responses:
		'200':
		description: Successful operation
		description: Successful operation.
		content:
		application/json:
		schema:
		$ref: '#/components/schemas/Trackable'
		'400':
		description: Invalid UUID supplied
		$ref: '#/components/responses/400_InvalidUUID'
		'404':
		description: Trackable not found
		$ref: '#/components/responses/404_NotFoundUUID'
		delete:
		summary: Deletes a trackable
		summary: Deletes a trackable.
		operationId: deleteTrackable
		tags:
		- trackables
		parameters:
		- name: trackableUUID
		in: path
		description: trackable UUID to delete
		description: Trackable UUID to delete.
		required: true
		schema:
		type: string
		format: uuid
		responses:
		'200':
		description: OK
		description: OK, delete successful.
		'400':
		description: Invalid UUID supplied
		$ref: '#/components/responses/400_InvalidUUID'
		'404':
		description: trackable not found
		$ref: '#/components/responses/404_NotFoundUUID'

		#################
		# WORLD ANCHORS #
		#################
		/worldAnchors:
		post:
		summary: Create a world anchor
		summary: Create a world anchor.
		operationId: addWorldAnchor
		tags:
		- 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:
		@@ -144,92 +160,95 @@ paths:
		$ref: '#/components/schemas/WorldAnchor'
		responses:
		'200':
		description: OK returns the UUID of the World Anchor defined by the world storage.
		description: OK, returns the UUID of the World Anchor defined by the world storage.
		content:
		text/plain:
		schema:
		type: string
		'201':
		description: Null response
		default:
		description: unexpected error
		content:
		application/json:
		schema:
		$ref: '#/components/schemas/Error'
		description: Null response.
		'400':
		$ref: '#/components/responses/400_BadRequest'
		'409':
		$ref: '#/components/responses/409_NotEmptyUUID'
		'default':
		$ref: '#/components/responses/4xx_UnexpectedError'
		get:
		summary: returns the list of all world anchors defined by the world storage.
		summary: Returns the list of all world anchors defined by the world storage.
		operationId: getWorldAnchors
		tags:
		- world anchors
		responses:
		200:
		description: OK returns all the world anchors defined by the world storage.
		'200':
		description: OK, returns all the world anchors defined by the world storage.
		content:
		application/json:
		schema:
		type : array
		items :
		$ref: "#/components/schemas/WorldAnchor"
		201:
		description: Null response
		'201':
		description: Null response.
		default:
		description: unexpected error
		content:
		application/json:
		schema:
		$ref: "#/components/schemas/Error"
		$ref: '#/components/responses/4xx_UnexpectedError'

		/worldAnchors/{worldAnchorUUID}:
		get:
		summary: Find a world anchor by his UUID
		summary: Find a world anchor by its UUID.
		operationId: getWorldAnchorById
		tags:
		- world anchors
		parameters:
		- name: trackableUUID
		- 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
		format: uuid
		responses:
		'200':
		description: Successful operation
		description: Successful operation.
		content:
		application/json:
		schema:
		$ref: '#/components/schemas/WorldAnchor'
		'400':
		description: Invalid UUID supplied
		$ref: '#/components/responses/400_InvalidUUID'
		'404':
		description: World Anchor not found
		$ref: '#/components/responses/404_NotFoundUUID'
		delete:
		summary: Deletes a world anchor
		summary: Deletes a world anchor.
		operationId: deleteWorldAnchor
		tags:
		- world anchors
		parameters:
		- name: trackableUUID
		- name: worldAnchorUUID
		in: path
		description: world anchor UUID to delete
		description: World anchor UUID to delete.
		required: true
		schema:
		type: string
		format: uuid
		responses:
		'200':
		description: OK
		description: OK, delete successful.
		'400':
		description: Invalid UUID supplied
		$ref: '#/components/responses/400_InvalidUUID'
		'404':
		description: World anchor not found
		$ref: '#/components/responses/404_NotFoundUUID'

		###############
		# WORLD LINKS #
		###############
		/worldLinks:
		post:
		summary: Create a link between world anchors and trackables
		summary: Create a link between world anchors and trackables.
		operationId: addWorldLink
		tags:
		- world links
		requestBody:
		description: the link to be added to the world storage
		description: The link to be added to the world storage.
		required: true
		content:
		application/json:
		@@ -240,26 +259,26 @@ paths:
		$ref: '#/components/schemas/WorldLink'
		responses:
		'200':
		description: OK returns the UUID of the link defined by the world storage.
		description: OK, returns the UUID of the link defined by the world storage.
		content:
		text/plain:
		schema:
		type: string
		'201':
		description: Null response
		default:
		description: unexpected error
		content:
		application/json:
		schema:
		$ref: '#/components/schemas/Error'
		'400':
		$ref: '#/components/responses/400_BadRequest'
		'409':
		$ref: '#/components/responses/409_NotEmptyUUID'
		'default':
		$ref: '#/components/responses/4xx_UnexpectedError'
		get:
		summary: returns the list of all links defined by the world storage.
		summary: Returns the list of all links defined by the world storage.
		operationId: getWorldLinks
		tags:
		- world links
		responses:
		200:
		'200':
		description: OK returns all the worldLinks defined by the world storage.
		content:
		application/json:
		@@ -267,40 +286,38 @@ paths:
		type : array
		items :
		$ref: "#/components/schemas/WorldLink"
		201:
		'201':
		description: Null response
		default:
		description: unexpected error
		content:
		application/json:
		schema:
		$ref: "#/components/schemas/Error"
		$ref: '#/components/responses/4xx_UnexpectedError'

		/worldLinks/{worldLinkUUID}:
		get:
		summary: Find a link by his ID
		summary: Find a link by its UUID.
		operationId: getWorldLinkById
		tags:
		- world links
		parameters:
		- name: worldLinkUUID
		in: path
		description: ID of the link to retrieve
		description: UUID of the link to retrieve.
		required: true
		schema:
		type: string
		format: uuid
		responses:
		'200':
		description: Successful operation
		description: Successful operation.
		content:
		application/json:
		schema:
		$ref: '#/components/schemas/WorldLink'
		'400':
		description: Invalid ID supplied
		$ref: '#/components/responses/400_InvalidUUID'
		'404':
		description: World Link not found
		$ref: '#/components/responses/404_NotFoundUUID'
		delete:
		summary: Deletes a worldLink
		summary: Deletes a worldLink.
		operationId: deleteWorldLink
		tags:
		- world links
		@@ -311,14 +328,60 @@ paths:
		required: true
		schema:
		type: string
		format: uuid
		responses:
		'200':
		description: OK
		'400':
		description: Invalid ID supplied
		$ref: '#/components/responses/400_InvalidUUID'
		'404':
		$ref: '#/components/responses/404_NotFoundUUID'

		/worldLinks/attached/{worldLinkUUID}:
		get:
		summary: Retrieve end objects connected to this world link by its UUID.
		operationId: getAttachedObjectsFromUUID
		tags:
		- world links
		parameters:
		- name: worldLinkUUID
		in: path
		description: UUID of the link from which you will retrieve the end objects.
		required: true
		schema:
		type: string
		format: uuid
		responses:
		'200':
		description: Successful operation.
		content:
		application/json:
		schema:
		$ref: '#/components/schemas/AttachedObjects'
		'400':
		$ref: '#/components/responses/400_InvalidUUID'
		'404':
		description: link not found
		$ref: '#/components/responses/404_NotFoundUUID'

		# COMPONENTS ###############################################
		components:
		#-------------------------------
		# Reusable operation parameters
		#-------------------------------
		parameters:
		UUIDParams:
		name: UUID
		in: path
		required: true
		description: A Universally Unique IDentifier identifying the object
		schema:
		type: string
		format: uuid
		default: "00000000-0000-0000-0000-000000000000"

		#-------------------------------
		# Reusable schemas (data models)
		#-------------------------------
		schemas:
		Trackable:
		type: object
		@@ -333,17 +396,17 @@ components:
		- keyvalueTagList
		properties:
		UUID:
		description: A Universally Unique IDentifier identifying the trackable (RFC 4122)
		description: A Universally Unique IDentifier identifying the trackable (RFC 4122).
		type: string
		format: uuid
		example: fa8bbe40-8052-11ec-a8a3-0242ac120002
		creatorUUID:
		description: A Universally Unique IDentifier identifying the creator of the trackable (a person, a team or a company)
		description: A Universally Unique IDentifier identifying the creator of the trackable (a person, a team or a company).
		type: string
		format: uuid
		example: c75f6324-77a0-11ec-90d6-0242ac120003
		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, OTHER]
		example: FIDUCIAL_MARKER
		@@ -362,6 +425,7 @@ components:
		$ref: '#/components/schemas/Size'
		keyvalueTags:
		$ref: '#/components/schemas/KeyvalueTagList'

		WorldAnchor:
		type: object
		required:
		@@ -372,12 +436,12 @@ components:
		- keyvalueTagList
		properties:
		UUID:
		description: A Universally Unique IDentifier identifying the world anchor
		description: A Universally Unique IDentifier identifying the world anchor (RFC 4122).
		type: string
		format: uuid
		example: ce8ccd80-56ee-2a5c-a8a3-0242ac150d002
		creatorUUID:
		description: A Universally Unique IDentifier identifying the creator of the world anchor
		description: A Universally Unique IDentifier identifying the creator of the world anchor.
		type: string
		format: uuid
		example: c75f6324-77a0-11ec-90d6-0242ac120003
		@@ -389,6 +453,7 @@ components:
		$ref: '#/components/schemas/Size'
		keyvalueTags:
		$ref: '#/components/schemas/KeyvalueTagList'

		WorldLink:
		type: object
		required:
		@@ -401,22 +466,22 @@ components:
		- keyvalueTags
		properties:
		UUID:
		description: A Universally Unique IDentifier identifying the link
		description: A Universally Unique IDentifier identifying the link (RFC 4122).
		type: string
		format: uuid
		example: ce8ccd80-56ee-2a5c-a8a3-0242ac150d002
		creatorUUID:
		description: A Universally Unique IDentifier identifying the creator of the link
		description: A Universally Unique IDentifier identifying the creator of the link.
		type: string
		format: uuid
		example: c75f6324-77a0-11ec-90d6-0242ac120003
		UUIDFrom:
		description: A Universally Unique IDentifier identifying a world anchor or trackable
		description: A Universally Unique IDentifier identifying a world anchor or trackable.
		type: string
		format: uuid
		example: ce8ccd80-56ee-2a5c-a8a3-0242ac150d002
		UUIDTo:
		description: A Universally Unique IDentifier identifying a world anchor or trackable
		description: A Universally Unique IDentifier identifying a world anchor or trackable.
		type: string
		format: uuid
		example: ce8ccd80-56ee-2a5c-a8a3-0242ac150d002
		@@ -430,6 +495,36 @@ components:
		description: List of additional parameters to be stored
		$ref: '#/components/schemas/KeyvalueTagList'
		example: { "LinkType" : ["Hierarchy"]}

		AttachedObjects:
		type: object
		required:
		- UUID
		- UUIDFrom
		- UUIDTo
		- TypeFrom
		- TypeTo
		properties:
		UUID:
		description: A Universally Unique IDentifier identifying the link.
		type: string
		format: uuid
		example: ce8ccd80-56ee-2a5c-a8a3-0242ac150d002
		UUIDFrom:
		description: A Universally Unique IDentifier identifying a world anchor or trackable.
		type: string
		format: uuid
		example: ce8ccd80-56ee-2a5c-a8a3-0242ac150d002
		UUIDTo:
		description: A Universally Unique IDentifier identifying a world anchor or trackable.
		type: string
		format: uuid
		example: ce8ccd80-56ee-2a5c-a8a3-0242ac150d002
		TypeFrom:
		$ref: '#/components/schemas/ObjectType'
		TypeTo:
		$ref: '#/components/schemas/ObjectType'

		EncodingInformationStructure:
		required:
		- dataFormat
		@@ -444,6 +539,7 @@ components:
		description: The version of the format
		type: string
		example : "1.01"

		Transform3D:
		description: Coordinate reference system of the world anchor, a 4*4 matrix (rowmajor) represented by a float vector
		type: array
		@@ -456,13 +552,21 @@ components:
		4, 4, 4, 2,
		1, 0,-2, 1,
		-1,-2, 0, 0]

		ObjectType:
		description: Type of an world representaion object.
		type: string
		enum: [Trackable, WorldAnchor, WorldLink]
		example: Trackable

		UnitSystem:
		description: Unit of length
		description: Unit of length.
		type: string
		enum: [MM, CM, DM, M, DAM, HM, KM, INCH, FOOT, YARD, MILE]
		example: M

		Size:
		description: Size {width, length, depth}
		description: Size {width, length, depth}.
		type: array
		items:
		type: number
		@@ -470,6 +574,7 @@ components:
		minItems: 3
		maxItems: 3
		example: [1,5,0]

		KeyvalueTagList:
		description: List of additional parameters to be stored with the trackable.
		type: object
		@@ -479,6 +584,7 @@ components:
		type: string
		minItems: 1
		example: { "Place" : ["Museum 1"], "room" : ["B4"]}

		Error:
		required:
		- code
		@@ -489,3 +595,50 @@ components:
		format: int32
		message:
		type: string
		#-------------------------------
		# Reusable responses
		#-------------------------------
		responses:
		#######################
		# 1xx : Informational #
		#######################

		#################
		# 2xx : Success #
		#################

		#####################
		# 3xx : Redirection #
		#####################

		#######################
		# 4xx : Client Errors #
		#######################
		400_BadRequest:
		description: Bad request.

		400_InvalidUUID:
		description: Invalid UUID supplied.

		404_NotFoundUUID:
		description: Not found, could not find UUID in database.

		409_NotEmptyUUID:
		description: Invalid UUID, id must be a Nil value.

		4xx_UnexpectedError: # Can be referenced as '#/components/responses/GenericError'
		description: Unexpected error.
		content:
		application/json:
		schema:
		$ref: '#/components/schemas/Error'

		########################
		# 5xx : Server Errors #
		########################
		5xx_UnexpectedError:
		description: Unexpected server error.
		content:
		application/json:
		schema:
		$ref: '#/components/schemas/Error'

README.md

+24 −11

File changed.

Preview size limit exceeded, changes collapsed.