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	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.3
		version: 0.0.4
		title: World Storage API
		description: API ensuring interoperability between an authoring tool and a World Storage service
		license:
		@@ -12,155 +27,524 @@ paths:
		/ping:
		get:
		summary: Test the server availability
		operationId: getPing
		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:
		schema:
		$ref: '#/components/schemas/trackable'
		application/xml:
		schema:
		$ref: '#/components/schemas/trackable'
		$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.
		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
		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:
		$ref: '#/components/schemas/Error'
		type : array
		items :
		$ref: "#/components/schemas/Trackable"
		'201':
		description: Null response.
		default:
		$ref: '#/components/responses/4xx_UnexpectedError'

		/trackables/{trackableUUID}:
		get:
		summary: returns the list of all trackables defined by the world storage.
		operationId: getTrackables
		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 Trackables 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/trackable"
		201:
		description: Null response
		$ref: "#/components/schemas/WorldAnchor"
		'201':
		description: Null response.
		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:
		application/json:
		schema:
		$ref: "#/components/schemas/Error"
		/trackables/{trackableId}:
		$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: Find a trackable by his ID
		operationId: getTrackableById
		summary: Returns the list of all links defined by the world storage.
		operationId: getWorldLinks
		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:
		- name: trackableId
		- name: worldLinkUUID
		in: path
		description: ID of the trackable 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/trackable'
		$ref: '#/components/schemas/WorldLink'
		'400':
		description: "Invalid ID supplied"
		$ref: '#/components/responses/400_InvalidUUID'
		'404':
		description: "Trackable not found"
		$ref: '#/components/responses/404_NotFoundUUID'
		delete:
		summary: Deletes a trackable
		operationId: deleteTrackable
		summary: Deletes a worldLink.
		operationId: deleteWorldLink
		tags:
		- trackables
		- world links
		parameters:
		- name: trackableId
		- name: worldLinkUUID
		in: path
		description: trackable id to delete
		description: link id to delete
		required: true
		schema:
		type: string
		format: uuid
		responses:
		'200':
		description: OK
		'400':
		description: Invalid ID supplied
		$ref: '#/components/responses/400_InvalidUUID'
		'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:
		#-------------------------------
		# 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:
		Trackable:
		type: object
		required:
		- UID
		- creatorUID
		- creatorUUID
		- trackableType
		- trackableEncodingInformation
		- trackablePayload
		- unitSystem
		- trackableDimension
		- localCRS
		- unit
		- trackableSize
		- keyvalueTagList
		properties:
		UID:
		description: A Universally Unique IDentifier identifying the trackable
		UUID:
		description: A Universally Unique IDentifier identifying the trackable (RFC 4122).
		type: string
		format: uuid
		example: c75f6324-77a0-11ec-90d6-0242ac120001
		creatorUID:
		description: A Universally Unique IDentifier identifying the creator of the trackable
		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
		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:
		description: Identifies targeted framework and version of the format.
		$ref: '#/components/schemas/encodingInformationStructure'
		$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:
		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
		minItems: 16
		maxItems: 16
		@@ -171,13 +555,21 @@ components:
		4, 4, 4, 2,
		1, 0, -2, 1,
		-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
		enum: [MM, CM, DM, M, DAM, HM, KM, INCH, FOOT, YARD, MILE]
		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
		items:
		type: number
		@@ -185,7 +577,8 @@ components:
		minItems: 3
		maxItems: 3
		example: [1,5,0]
		keyvalueTagList:

		KeyvalueTagList:
		description: List of additional parameters to be stored with the trackable.
		type: object
		additionalProperties:
		@@ -193,21 +586,8 @@ components:
		items:
		type: string
		minItems: 1
		example: { "author" : ["james","donovan"], "image" : ["skater"]}
		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"
		example: { "Place" : ["Museum 1"], "room" : ["B4"]}

		Error:
		required:
		- code
		@@ -218,3 +598,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'

openapitools.json

+1 −1

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

readme.md

+24 −1

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

		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`"

		#### - 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`:
		add:
		```
		@@ -49,6 +68,10 @@ at the value that is to become the MongoDB ID, add:
		[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
		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.