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	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	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	Diff line number	Diff line
		Subproject commit aaf4295668539d5ce805dfd9fa1c4679377e8038