first checkin for version 0.0.4 (27dc7e5f) · Commits · ARF / World Storage API Helpers / World Storage ASP.NET Server

OpenAPI.yaml

+503 −76

Original line number	Original line	Diff line number	Diff line
	openapi: "3.0.0"		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:		info:
	version: 0.0.3		version: 0.0.4
	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:
	@@ -12,155 +27,524 @@ paths:
	/ping:		/ping:
	get:		get:
	summary: Test the server availability		summary: Test the server availability
			operationId: getPing
	responses:		responses:
	'200':		'200':
	description: OK		description: OK, world storage alive.
	/admin:		/admin:
	get:		get:
	summary: Get the version of the API		summary: Get the version of the API.
	operationId: getVersion		operationId: getVersion
	responses:		responses:
	'200':		'200':
	description: OK world storage.		description: OK, world storage ready.
	content:		content:
	text/plain:		text/plain:
	schema:		schema:
	type: string		type: string

			##############
			# TRACKABLES #
			##############
	/trackables:		/trackables:
	post:		post:
	summary: Create a trackable		summary: Create a trackable.
	operationId: addTrackable		operationId: addTrackable
	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:		#application/xml:
	schema:		# schema:
	$ref: '#/components/schemas/trackable'		# $ref: '#/components/schemas/Trackable'
	responses:		responses:
	'200':		'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:		content:
	text/plain:		text/plain:
	schema:		schema:
	type: string		type: string
	'201':		'201':
	description: Null response		description: Null response.
	default:		'400':
	description: unexpected error		$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:		content:
	application/json:		application/json:
	schema:		schema:
	$ref: '#/components/schemas/Error'		type : array
			items :
			$ref: "#/components/schemas/Trackable"
			'201':
			description: Null response.
			default:
			$ref: '#/components/responses/4xx_UnexpectedError'

			/trackables/{trackableUUID}:
	get:		get:
	summary: returns the list of all trackables defined by the world storage.		summary: Find a trackable by its UUID.
	operationId: getTrackables		operationId: getTrackableById
	tags:		tags:
	- trackables		- 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:		responses:
	200:		'200':
	description: OK returns all the Trackables defined by the world storage.		description: OK, returns all the world anchors defined by the world storage.
	content:		content:
	application/json:		application/json:
	schema:		schema:
	type : array		type : array
	items :		items :
	$ref: "#/components/schemas/trackable"		$ref: "#/components/schemas/WorldAnchor"
	201:		'201':
	description: Null response		description: Null response.
	default:		default:
	description: unexpected error		$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:		content:
	application/json:		application/json:
	schema:		schema:
	$ref: "#/components/schemas/Error"		$ref: '#/components/schemas/WorldAnchor'
	/trackables/{trackableId}:		'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:		get:
	summary: Find a trackable by his ID		summary: Returns the list of all links defined by the world storage.
	operationId: getTrackableById		operationId: getWorldLinks
	tags:		tags:
	- trackables		- 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:		parameters:
	- name: trackableId		- name: worldLinkUUID
	in: path		in: path
	description: ID of the trackable to retrieve		description: UUID of the link to retrieve.
	required: true		required: true
	schema:		schema:
	type: string		type: string
			format: uuid
	responses:		responses:
	'200':		'200':
	description: "successful operation"		description: Successful operation.
	content:		content:
	application/json:		application/json:
	schema:		schema:
	$ref: '#/components/schemas/trackable'		$ref: '#/components/schemas/WorldLink'
	'400':		'400':
	description: "Invalid ID supplied"		$ref: '#/components/responses/400_InvalidUUID'
	'404':		'404':
	description: "Trackable not found"		$ref: '#/components/responses/404_NotFoundUUID'
	delete:		delete:
	summary: Deletes a trackable		summary: Deletes a worldLink.
	operationId: deleteTrackable		operationId: deleteWorldLink
	tags:		tags:
	- trackables		- world links
	parameters:		parameters:
	- name: trackableId		- name: worldLinkUUID
	in: path		in: path
	description: trackable id to delete		description: link id to delete
	required: true		required: true
	schema:		schema:
	type: string		type: string
			format: uuid
	responses:		responses:
	'200':		'200':
	description: OK		description: OK
	'400':		'400':
	description: Invalid ID supplied		$ref: '#/components/responses/400_InvalidUUID'
	'404':		'404':
	description: trackable not found		$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:		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:		schemas:
	trackable:		Trackable:
	type: object		type: object
	required:		required:
	- UID		- creatorUUID
	- creatorUID
	- trackableType		- trackableType
	- trackableEncodingInformation		- trackableEncodingInformation
	- trackablePayload		- trackablePayload
	- unitSystem		- localCRS
	- trackableDimension		- unit
			- trackableSize
	- keyvalueTagList		- keyvalueTagList
	properties:		properties:
	UID:		UUID:
	description: A Universally Unique IDentifier identifying the trackable		description: A Universally Unique IDentifier identifying the trackable (RFC 4122).
	type: string		type: string
	format: uuid		format: uuid
	example: c75f6324-77a0-11ec-90d6-0242ac120001		example: fa8bbe40-8052-11ec-a8a3-0242ac120002
	creatorUID:		creatorUUID:
	description: A Universally Unique IDentifier identifying the creator of the trackable		description: A 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: c75f6324-77a0-11ec-90d6-0242ac120003		example: c75f6324-77a0-11ec-90d6-0242ac120003
	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, OTHER]		enum: [FIDUCIAL_MARKER, IMAGE_MARKER, MAP, OTHER]
	example: FIDUCIAL_MARKER		example: FIDUCIAL_MARKER
	trackableEncodingInformation:		trackableEncodingInformation:
	description: Identifies targeted framework and version of the format.		$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"
	localCRS:		localCRS:
	description: Coordinate reference system of the trackable, a 4*4 matrix (rowmajor) represented by a float vector		$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		type: array
	minItems: 16		minItems: 16
	maxItems: 16		maxItems: 16
	@@ -171,13 +555,21 @@ components:
	4, 4, 4, 2,		4, 4, 4, 2,
	1, 0, -2, 1,		1, 0, -2, 1,
	-1, -2, 0, 0]		-1, -2, 0, 0]
	unitSystem:
	description: Unit of length		ObjectType:
			description: Type of an world representaion object.
			type: string
			enum: [Trackable, WorldAnchor, WorldLink]
			example: Trackable

			UnitSystem:
			description: Unit of length.
	type: string		type: string
	enum: [MM, CM, DM, M, DAM, HM, KM, INCH, FOOT, YARD, MILE]		enum: [MM, CM, DM, M, DAM, HM, KM, INCH, FOOT, YARD, MILE]
	example: M		example: M
	trackableDimension:
	description: Bounding box of the Trackable, {width, length, 0} for 2D trackables, {width, length, depth} for 3D trackables		Size:
			description: Size {width, length, depth}.
	type: array		type: array
	items:		items:
	type: number		type: number
	@@ -185,7 +577,8 @@ components:
	minItems: 3		minItems: 3
	maxItems: 3		maxItems: 3
	example: [1,5,0]		example: [1,5,0]
	keyvalueTagList:
			KeyvalueTagList:
	description: List of additional parameters to be stored with the trackable.		description: List of additional parameters to be stored with the trackable.
	type: object		type: object
	additionalProperties:		additionalProperties:
	@@ -193,21 +586,8 @@ components:
	items:		items:
	type: string		type: string
	minItems: 1		minItems: 1
	example: { "author" : ["james","donovan"], "image" : ["skater"]}		example: { "Place" : ["Museum 1"], "room" : ["B4"]}
	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"
	Error:		Error:
	required:		required:
	- code		- code
	@@ -218,3 +598,50 @@ components:
	format: int32		format: int32
	message:		message:
	type: string		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'

openapitools.json

+1 −1

Original line number	Original line	Diff line number	Diff line
	@@ -2,6 +2,6 @@
	"$schema": "node_modules/@openapitools/openapi-generator-cli/config.schema.json",		"$schema": "node_modules/@openapitools/openapi-generator-cli/config.schema.json",
	"spaces": 2,		"spaces": 2,
	"generator-cli": {		"generator-cli": {
	"version": "5.3.1"		"version": "5.3.0"
	}		}
	}		}

readme.md

+24 −1

Original line number	Original line	Diff line number	Diff line
	# Description of version 0.0.3		# Description of version 0.0.4

	auto-generated ASP.NET server code		auto-generated ASP.NET server code

	@@ -36,6 +36,25 @@ compare files in "`ControllersImpl`" with the corresponding files in "`Controlle

	methods should be the same with "`override`" instead of "`virtual`"		methods should be the same with "`override`" instead of "`virtual`"

			#### - if files are missing:
			copy them from folder `Controllers`, rename them (append `Impl`) and handle them like the already existing files, i.e.:
			change classnames by appending `Impl` to the original classnames (and change filenames accordingly) and inherit from original class in `Controllers` (instead of `ControllerBase`)

			and replace `virtual` by `override` with all methods.

			Add
			```
			using Org.OpenAPITools.Services;
			using MongoDB.Driver;
			```

			Add a private readonly service class variable like in the already existing files

			Add a constructor with this service class variable like in the already existing files

			remove sample code and replace it by using the appropriate methods of the corresponding classes in the folder `Services`
			(which you may be have to create)

	### - folder `Models`:		### - folder `Models`:
	add:		add:
	```		```
	@@ -49,6 +68,10 @@ at the value that is to become the MongoDB ID, add:
	[BsonRepresentation(BsonType.String)]		[BsonRepresentation(BsonType.String)]
	```		```

			### - folder `Services`
			the folder `Services` should contain one common class with the DatabaseSettings (`DatabaseSettings.cs`) and one with the database-access-methods (create, get, update, remove) for each API. If some are missing create them like the ones you find there. Be aware to add the reference to these in the file `startup.cs` in this case.

			the naming in the DatabaseSettings is the same as defined in `appsettings.json`, which you have to extend when creating new classes in this folder. changed `appsettings.json` in the folder `docker` accordingly. Make sure that the ConnectionString for the database contains the correct IP address as specified in `docker-compose.yml`.

	# MongoDB		# MongoDB
	if you don't have a MongoDB, follow the instructions in `readme.txt` in `server/programs/MongoDB`		if you don't have a MongoDB, follow the instructions in `readme.txt` in `server/programs/MongoDB`

server/src/Org.OpenAPITools/ControllersImpl/DefaultApiImpl.cs

+19 −18

File changed.

Preview size limit exceeded, changes collapsed.

server/src/Org.OpenAPITools/ControllersImpl/TrackablesApiImpl.cs

+55 −35

File changed.

Preview size limit exceeded, changes collapsed.