- Add new header sessionID to identify the running AR session (0925684a) · Commits · ARF - Augmented Reality Framework / ARF

API/worldanalysis/worldanalysisopenapi.yaml

+247 −113

Original line number	Diff line number	Diff line
		@@ -69,6 +69,10 @@ paths:
		name: token
		schema:
		$ref: '#/components/schemas/Token'
		- in: header
		name: sessionID
		schema:
		$ref: '#/components/schemas/SessionID'
		requestBody:
		required: true
		content:
		@@ -85,17 +89,75 @@ paths:

		/pose/{trackableOrAnchorUUID}:
		get:
		summary: Request the last pose of an AR device, an Anchor or a Trackable
		operationId: getLastPose
		summary: Request the last pose of a single Anchor or Trackable
		operationId: getPose
		description: Operation to retrieve the pose of an AR device in relation to a WorldAnchor or a Trackable (AR device pose), or conversely a Trackable or WorldAnchor in relation to the AR device (object pose).
		tags:
		- Pose
		parameters:
		- in: header
		name: token
		schema:
		$ref: '#/components/schemas/Token'
		- in: header
		name: sessionID
		schema:
		$ref: '#/components/schemas/SessionID'
		- name: trackableOrAnchorUUID
		in: path
		description: UUID of the Trackable or Anchor to check support
		description: UUID of the Trackable or Anchor to request
		required: true
		schema:
		type: string
		format: uuid
		example: "fa8bbe40-8052-11ec-a8a3-0242ac120002"
		- name: mode
		in: query
		description: Mode representing the context of the Relocalization information (AR device to WorldAnchor/Trackable or WorldAnchor/Trackable to AR device)
		required: true
		schema:
		$ref: '#/components/schemas/Mode'
		responses:
		'200':
		description: Successful operation.
		content:
		application/json:
		schema:
		$ref: '#/components/schemas/Pose'
		'400':
		$ref: '#/components/responses/400_BadRequest'
		'403':
		$ref: '#/components/responses/403_Forbidden'
		'404':
		$ref: '#/components/responses/404_NotFound'
		'405':
		$ref: '#/components/responses/405_NotSupported'
		'default':
		$ref: '#/components/responses/4xx_UnexpectedError'

		/poses:
		get:
		summary: Request the last pose of a batch of Anchor or Trackable
		operationId: getPoses
		description: Operation to retrieve the pose of an AR device in relation to a batch of WorldAnchor or a Trackable (AR device pose), or conversely a batch of Trackable or WorldAnchor in relation to the AR device (object pose).
		tags:
		- Pose
		parameters:
		- in: header
		name: token
		schema:
		$ref: '#/components/schemas/Token'
		- in: header
		name: sessionID
		schema:
		$ref: '#/components/schemas/SessionID'
		- name: uuid
		in: query
		description: UUID of the Trackable or Anchor to request
		required: true
		schema:
		type: array
		items:
		type: string
		format: uuid
		example: "fa8bbe40-8052-11ec-a8a3-0242ac120002"
		@@ -111,13 +173,18 @@ paths:
		content:
		application/json:
		schema:
		type: object
		properties:
		poses:
		type: array
		items:
		$ref: '#/components/schemas/Pose'
		'400':
		$ref: '#/components/responses/400_InvalidUUID'
		$ref: '#/components/responses/400_BadRequest'
		'403':
		$ref: '#/components/responses/403_ForbiddenUUID'
		$ref: '#/components/responses/403_Forbidden'
		'404':
		$ref: '#/components/responses/404_NotFoundUUID'
		$ref: '#/components/responses/404_NotFound'
		'405':
		$ref: '#/components/responses/405_NotSupported'
		'default':
		@@ -131,16 +198,21 @@ paths:
		tags:
		- Pose
		parameters:
		- name: token
		in: header
		- in: header
		name: token
		schema:
		$ref: '#/components/schemas/Token'
		- in: header
		name: sessionID
		schema:
		$ref: '#/components/schemas/SessionID'
		- name: target
		in: query
		description: UUID of the Trackable or Anchor to subscribe
		required: false
		schema:
		type: string
		type: array
		items:
		format: uuid
		example: "fa8bbe40-8052-11ec-a8a3-0242ac120002"
		requestBody:
		@@ -148,20 +220,25 @@ paths:
		content:
		application/json:
		schema:
		$ref: '#/components/schemas/SubscriptionRequest'
		oneOf:
		- $ref: '#/components/schemas/SubscriptionSingleRequest'
		- $ref: '#/components/schemas/SubscriptionMultipleRequest'

		responses:
		'200':
		description: Successful operation.
		content:
		application/json:
		schema:
		$ref: '#/components/schemas/Subscription'
		oneOf:
		- $ref: '#/components/schemas/SubscriptionSingle'
		- $ref: '#/components/schemas/SubscriptionMultiple'
		'400':
		$ref: '#/components/responses/400_InvalidUUID'
		$ref: '#/components/responses/400_BadRequest'
		'403':
		$ref: '#/components/responses/403_ForbiddenUUID'
		$ref: '#/components/responses/403_Forbidden'
		'404':
		$ref: '#/components/responses/404_NotFoundUUID'
		$ref: '#/components/responses/404_NotFound'
		'405':
		$ref: '#/components/responses/405_NotSupported'
		'default':
		@@ -180,6 +257,10 @@ paths:
		name: token
		schema:
		$ref: '#/components/schemas/Token'
		- in: header
		name: sessionID
		schema:
		$ref: '#/components/schemas/SessionID'
		- name: subscriptionUUID
		in: path
		description: Subscription UUID to retrieve.
		@@ -194,11 +275,11 @@ paths:
		content:
		application/json:
		schema:
		$ref: '#/components/schemas/Subscription'
		$ref: '#/components/schemas/SubscriptionSingle'
		'400':
		$ref: '#/components/responses/400_InvalidUUID'
		$ref: '#/components/responses/400_BadRequest'
		'404':
		$ref: '#/components/responses/404_NotFoundUUID'
		$ref: '#/components/responses/404_NotFound'
		put:
		summary: Update a subscription
		operationId: updateSubscription
		@@ -210,6 +291,10 @@ paths:
		name: token
		schema:
		$ref: '#/components/schemas/Token'
		- in: header
		name: sessionID
		schema:
		$ref: '#/components/schemas/SessionID'
		- name: subscriptionUUID
		in: path
		description: Subscription UUID to delete.
		@@ -243,11 +328,11 @@ paths:
		content:
		application/json:
		schema:
		$ref: '#/components/schemas/Subscription'
		$ref: '#/components/schemas/SubscriptionSingle'
		'400':
		$ref: '#/components/responses/400_InvalidUUID'
		$ref: '#/components/responses/400_BadRequest'
		'404':
		$ref: '#/components/responses/404_NotFoundUUID'
		$ref: '#/components/responses/404_NotFound'
		delete:
		summary: Remove a subscription to a given pose
		operationId: unsubscribeFromPose
		@@ -259,6 +344,10 @@ paths:
		name: token
		schema:
		$ref: '#/components/schemas/Token'
		- in: header
		name: sessionID
		schema:
		$ref: '#/components/schemas/SessionID'
		- name: subscriptionUUID
		in: path
		description: Subscription UUID to delete.
		@@ -276,9 +365,9 @@ paths:
		type: string
		example: "Subscription succesfuly deleted"
		'400':
		$ref: '#/components/responses/400_InvalidUUID'
		$ref: '#/components/responses/400_BadRequest'
		'404':
		$ref: '#/components/responses/404_NotFoundUUID'
		$ref: '#/components/responses/404_NotFound'

		/capabilities:
		get:
		@@ -292,6 +381,10 @@ paths:
		name: token
		schema:
		$ref: '#/components/schemas/Token'
		- in: header
		name: sessionID
		schema:
		$ref: '#/components/schemas/SessionID'
		responses:
		'200':
		description: Successful operation.
		@@ -320,6 +413,10 @@ paths:
		name: token
		schema:
		$ref: '#/components/schemas/Token'
		- in: header
		name: sessionID
		schema:
		$ref: '#/components/schemas/SessionID'
		- name: trackableOrAnchorUUID
		in: path
		description: UUID of the Trackable or Anchor to check support
		@@ -340,11 +437,11 @@ paths:
		capability:
		$ref: '#/components/schemas/Capability'
		'400':
		$ref: '#/components/responses/400_InvalidUUID'
		$ref: '#/components/responses/400_BadRequest'
		'403':
		$ref: '#/components/responses/403_ForbiddenUUID'
		$ref: '#/components/responses/403_Forbidden'
		'404':
		$ref: '#/components/responses/404_NotFoundUUID'
		$ref: '#/components/responses/404_NotFound'
		'405':
		$ref: '#/components/responses/405_NotSupported'
		'default':
		@@ -363,6 +460,11 @@ components:
		example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJodHRwczovL2V4YW1wbGUuYXV0aDAuY29tLyIsImF1ZCI6Imh0dHBzOi8vYXBpLmV4YW1wbGUuY29tL2NhbGFuZGFyL3YxLyIsInN1YiI6InVzcl8xMjMiLCJpYXQiOjE0NTg3ODU3OTYsImV4cCI6MTQ1ODg3MjE5Nn0.CA7eaHjIHz5NxeIJoFK9krqaeZrPLwmMmgI_XiQiIkQ
		description: A string representing the token of the User.

		SessionID:
		type: string
		example: 4JA1xVJSYKE47UM7RKDrfUcTXlJ0wxSQ
		description: A string representing the session ID associated with the AR session.

		Pose:
		description: An element representing the result of the pose estimation of an AR device, a Trackable or a WorldAnchor by the World Analysis
		type: object
		@@ -416,7 +518,7 @@ components:
		type:
		description: Encoding type of the Pose
		type: string
		enum: [MATRIX, VECTORQUATERNION, GEODETIC]
		enum: [MATRIX, VECTOR_QUATERNION, GEODETIC]

		MatrixPoseValue:
		description: A pose value that is described with a 4*4 matrix
		@@ -563,7 +665,7 @@ components:
		type: number
		example : 30.0

		SubscriptionRequest:
		SubscriptionSingleRequest:
		description: Request when subscribing for pose update of a Trackable or a WorldAnchor
		type: object
		properties:
		@@ -572,6 +674,12 @@ components:
		type: string
		format: uuid
		example: "fa8bbe40-8052-11ec-a8a3-0242ac120002"
		targets:
		description: List of UUID of the Trackable or Anchor to subscribe
		type: array
		items:
		format: uuid
		example: [ "fa8bbe40-8052-11ec-a8a3-0242ac120002", "fa8bbe40-8052-11ec-a8a3-0242ac120003"]
		mode:
		description: Mode representing the context of the Relocalization information (AR device to WorldAnchor/Trackable or WorldAnchor/Trackable to AR device)
		$ref: '#/components/schemas/Mode'
		@@ -588,7 +696,32 @@ components:
		- target
		- mode

		Subscription:
		SubscriptionMultipleRequest:
		description: Request when subscribing for pose update of multiple Trackable or a WorldAnchor
		type: object
		properties:
		targets:
		description: List of UUID of the Trackable or Anchor to subscribe
		type: array
		items:
		format: uuid
		example: [ "fa8bbe40-8052-11ec-a8a3-0242ac120002", "fa8bbe40-8052-11ec-a8a3-0242ac120003"]
		mode:
		description: Mode representing the context of the Relocalization information (AR device to WorldAnchor/Trackable or WorldAnchor/Trackable to AR device)
		$ref: '#/components/schemas/Mode'
		validity:
		description: Subscription validity delay in millisecond
		type: integer
		example: 20000
		webhookUrl:
		description: Optional URL of your listening webhook for collecting the poses
		type: string
		default: null
		example: "http://myscenemanagementserver.com/poses"
		required:
		- mode

		SubscriptionSingle:
		description: Response when subscribing for pose update of a Trackable or a WorldAnchor
		type: object
		properties:
		@@ -617,6 +750,15 @@ components:
		type: string
		example: "wss://mywordanalysisserver.com/websocket/bdc83e6b-a89d-4b29-9c99-e9015d448b10"

		SubscriptionMultiple:
		description: Response when subscribing for pose update of multiple Trackable or a WorldAnchor
		type: object
		properties:
		subscriptions:
		type: array
		items:
		$ref: '#/components/schemas/SubscriptionSingle'

		Error:
		required:
		- code
		@@ -666,31 +808,23 @@ components:
		# 4xx : Client Errors #
		#######################
		400_BadRequest:
		description: Bad request.
		description: Bad/Invalid request.
		content:
		text/plain:
		schema:
		type: string
		example: "Bad request"

		400_InvalidUUID:
		description: Invalid UUID supplied.
		content:
		text/plain:
		schema:
		example: "The format of the UUID is incorrect"
		type: string

		403_ForbiddenUUID:
		description: Not allowed to access this UUID
		403_Forbidden:
		description: Not allowed.
		content:
		text/plain:
		schema:
		type: string
		example: "Not allowed"

		404_NotFoundUUID:
		description: Not found, could not find UUID in database.
		404_NotFound:
		description: Not found.
		content:
		text/plain:
		schema:
		@@ -698,7 +832,7 @@ components:
		example: "Not found"

		405_NotSupported:
		description: Feature not supported.
		description: Not supported.
		content:
		text/plain:
		schema: