OpenAPI arf005 file as submodule (76ff6ad7) · Commits · ARF / World Storage API Helpers / World Storage ASP.NET Server

.gitmodules

0 → 100644

+3 −0

Original line number	Original line	Diff line number	Diff line
			[submodule "arf005"]
			path = arf005
			url = git@forge.etsi.org:arf/arf005.git

OpenAPI.yaml

deleted100644 → 0

+0 −647

Original line number	Original line	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/
	#
	# Last Version: 04.03.2022
	#
	info:
	version: 0.0.4
	title: World Storage API
	description: API ensuring interoperability between an authoring tool and a World Storage service
	license:
	name: BSD-3-clause
	url: https://opensource.org/licenses/BSD-3-Clause
	servers:
	- url: http://localhost:8080
	paths:
	/ping:
	get:
	summary: Test the server availability
	operationId: getPing
	responses:
	'200':
	description: OK, world storage alive.
	/admin:
	get:
	summary: Get the version of the API.
	operationId: getVersion
	responses:
	'200':
	description: OK, world storage ready.
	content:
	text/plain:
	schema:
	type: string

	##############
	# TRACKABLES #
	##############
	/trackables:
	post:
	summary: Create a trackable.
	operationId: addTrackable
	tags:
	- trackables
	requestBody:
	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
	'201':
	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.
	operationId: getTrackables
	tags:
	- trackables
	responses:
	'200':
	description: OK, returns all the Trackables defined by the world storage.
	content:
	application/json:
	schema:
	type : array
	items :
	$ref: "#/components/schemas/Trackable"
	'201':
	description: Null response.
	default:
	$ref: '#/components/responses/4xx_UnexpectedError'

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

	#################
	# WORLD ANCHORS #
	#################
	/worldAnchors:
	post:
	summary: Create a world anchor.
	operationId: addWorldAnchor
	tags:
	- world anchors
	requestBody:
	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.
	content:
	text/plain:
	schema:
	type: string
	'201':
	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.
	operationId: getWorldAnchors
	tags:
	- world anchors
	responses:
	'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.
	default:
	$ref: '#/components/responses/4xx_UnexpectedError'

	/worldAnchors/{worldAnchorUUID}:
	get:
	summary: Find a world anchor by its UUID.
	operationId: getWorldAnchorById
	tags:
	- world anchors
	parameters:
	- name: worldAnchorUUID
	in: path
	description: UUID of the world anchor to retrieve.
	required: true
	schema:
	type: string
	format: uuid
	responses:
	'200':
	description: Successful operation.
	content:
	application/json:
	schema:
	$ref: '#/components/schemas/WorldAnchor'
	'400':
	$ref: '#/components/responses/400_InvalidUUID'
	'404':
	$ref: '#/components/responses/404_NotFoundUUID'
	delete:
	summary: Deletes a world anchor.
	operationId: deleteWorldAnchor
	tags:
	- world anchors
	parameters:
	- name: worldAnchorUUID
	in: path
	description: World anchor UUID to delete.
	required: true
	schema:
	type: string
	format: uuid
	responses:
	'200':
	description: OK, delete successful.
	'400':
	$ref: '#/components/responses/400_InvalidUUID'
	'404':
	$ref: '#/components/responses/404_NotFoundUUID'

	###############
	# WORLD LINKS #
	###############
	/worldLinks:
	post:
	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.
	required: true
	content:
	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.
	content:
	text/plain:
	schema:
	type: string
	'201':
	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 links defined by the world storage.
	operationId: getWorldLinks
	tags:
	- world links
	responses:
	'200':
	description: OK returns all the worldLinks defined by the world storage.
	content:
	application/json:
	schema:
	type : array
	items :
	$ref: "#/components/schemas/WorldLink"
	'201':
	description: Null response
	default:
	$ref: '#/components/responses/4xx_UnexpectedError'

	/worldLinks/{worldLinkUUID}:
	get:
	summary: Find a link by its UUID.
	operationId: getWorldLinkById
	tags:
	- world links
	parameters:
	- name: worldLinkUUID
	in: path
	description: UUID of the link to retrieve.
	required: true
	schema:
	type: string
	format: uuid
	responses:
	'200':
	description: Successful operation.
	content:
	application/json:
	schema:
	$ref: '#/components/schemas/WorldLink'
	'400':
	$ref: '#/components/responses/400_InvalidUUID'
	'404':
	$ref: '#/components/responses/404_NotFoundUUID'
	delete:
	summary: Deletes a worldLink.
	operationId: deleteWorldLink
	tags:
	- world links
	parameters:
	- name: worldLinkUUID
	in: path
	description: link id to delete
	required: true
	schema:
	type: string
	format: uuid
	responses:
	'200':
	description: OK
	'400':
	$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':
	$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
	required:
	- creatorUUID
	- trackableType
	- trackableEncodingInformation
	- trackablePayload
	- localCRS
	- unit
	- trackableSize
	- keyvalueTagList
	properties:
	UUID:
	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).
	type: string
	format: uuid
	example: c75f6324-77a0-11ec-90d6-0242ac120003
	trackableType:
	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
	trackableEncodingInformation:
	$ref: '#/components/schemas/EncodingInformationStructure'
	trackablePayload:
	description: The data provided to create the trackable in a specific format handled by the World Storage service.
	type: string
	format: byte
	example: "10110101"
	localCRS:
	$ref: '#/components/schemas/Transform3D'
	unit:
	$ref: '#/components/schemas/UnitSystem'
	trackableSize:
	$ref: '#/components/schemas/Size'
	keyvalueTags:
	$ref: '#/components/schemas/KeyvalueTagList'

	WorldAnchor:
	type: object
	required:
	- creatorUUID
	- localCRS
	- unit
	- worldAnchorSize
	- keyvalueTagList
	properties:
	UUID:
	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.
	type: string
	format: uuid
	example: c75f6324-77a0-11ec-90d6-0242ac120003
	localCRS:
	$ref: '#/components/schemas/Transform3D'
	unit:
	$ref: '#/components/schemas/UnitSystem'
	worldAnchorSize:
	$ref: '#/components/schemas/Size'
	keyvalueTags:
	$ref: '#/components/schemas/KeyvalueTagList'

	WorldLink:
	type: object
	required:
	- creatorUUID
	- UUIDFrom
	- UUIDTo
	- transform
	- unit
	- linkSize
	- keyvalueTags
	properties:
	UUID:
	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.
	type: string
	format: uuid
	example: c75f6324-77a0-11ec-90d6-0242ac120003
	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
	transform:
	$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"]}

	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
	- version
	properties:
	dataFormat:
	description: Identifier of the target framework
	type: string
	enum: [HOLOLENS, ARKIT, ARCORE]
	example : "HOLOLENS"
	version:
	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
	minItems: 16
	maxItems: 16
	items:
	type: number
	format: float
	example: [-2, 1, -3, 4,
	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.
	type: string
	enum: [MM, CM, DM, M, DAM, HM, KM, INCH, FOOT, YARD, MILE]
	example: M

	Size:
	description: Size {width, length, depth}.
	type: array
	items:
	type: number
	format: double
	minItems: 3
	maxItems: 3
	example: [1,5,0]

	KeyvalueTagList:
	description: List of additional parameters to be stored with the trackable.
	type: object
	additionalProperties:
	type: array
	items:
	type: string
	minItems: 1
	example: { "Place" : ["Museum 1"], "room" : ["B4"]}

	Error:
	required:
	- code
	- message
	properties:
	code:
	type: integer
	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'

arf005 @ aaf42956

Original line number	Original line	Diff line number	Diff line
			Subproject commit aaf4295668539d5ce805dfd9fa1c4679377e8038

Admin message