XRHeath Developer API Documentation
This guide will help you get started with XRHealth API. XRHealth api will enable you to store sessions data and graphs on XRHealth servers and enable your users to view their results on XRHealth Web portal.
Our API is organized around REST and has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses.
Sandbox API is accessible for integration and testing.
API data flow on production environment
In order to save sessions data on XRHealth servers on production environment you will need to implement only 1 API route in your application: POST /api/developer/workout-sessions
The overall process is as follows:
- You as a developer will get an incoming Deep-link on application start-up with the following JSON structure:
{ "access_token": "14klkjerj2343lkjr3l4", "server_url": "https://api.portal.consumer-qa.xr.health/", "patient_ID": "13" }
- The "server_url" will be used for the POST API call.
- The "access_token" will be used for the Authorization Bearer access token - The token holds all the required information for the specific logged in user going over to your application.
- Once the session is uploaded correctly to our servers it will be visualized in our web portal to the client.
Save New Workout Session to server
Saving a new workout session to server is the only REST API call you will need to implement on production environment. The other 2 API routes in this documentation are for testing purposes.
For Development use the following URL to post Workout Session: https://api.portal.consumer-dev.xr.health
For Integration / production you use the URL from the deep link to post Workout Session.
Save New Workout Session in production
How to get authorization token
Developer access token needs for saving and getting workout session info. By default you will get the token in a JSON message through Oculus App Deep-linking mechanism.
More information about Oculus Deep-linking you can get on https://developer.oculus.com/documentation/platform/latest/concepts/dg-deeplinking/
Front-end visualization on the web-portal defines the different limitations on JSON size and structure.
How to save new workout session
For saving new workout session result use POST /api/developer/workout-sessions endpoint with:
Headers
-
Content-typerequiredapplication/x-www-form-urlencoded or application/json
-
AuthorizationrequiredBearer access token
Parameters
-
durationrequiredWorkout session duration in seconds.
-
epocStartTimerequiredCreation time in timestamp (milliseconds).
-
scorerequiredA score of the new session.
-
levelPlannedParamsrequiredJSON with workout session game settings.
-
softwareVersionrequiredString provided by 3rd party developer to indicate 3rd party version number.
-
resultDatarequiredJSON with workout session results
Parameters clarification
-
levelPlannedParams - This field enables you to send your application VR game settings for this specific Workout session. Game settings can be different settings according to your needs. Examples: Difficulty, Speed, etc. The field should be a JSON and can have up to 7 settings parameters in a format of "{"Key": Value}". For example the you can send: "{"Level": "Basic"}". -
- KEY - string size must to be up to 25 characters - The key represents the actual setting definition that eventually will be visualized to the end user.
- VALUE - string size up to 15 characters.
-
JSON example:
{ "SpeedLevel": "0", "SessionDuration": "8", "Difficulty": "Basic", "GameMode": "Enabled" }
- UI view example:
resultData - data summary and graphs. The JSON consist of two parts - calculatedData and graphEvents.- calculatedData - Session summary. will contain the average results for session for different calculated indicators (upper screenshot). You will be able to send up to 5 results.
- Structure - list of name,value,unit objects {"calculatedData": {"name":"someName","value":"60","unit":"%"}...}
- Limitation - The "name" value can be up to 25 characters. The sum of "value" and "unit" value can be up to 12 characters.
- JSON example:
- Not valid! the sum of value and unit is more than 12 characters
{ "name":"hits", "value":"123456789", "unit":"0123" }
- valid calculated Data
{ "name":"hits", "value":"60", "unit":"times" }
- Not valid! the sum of value and unit is more than 12 characters
- UI view example:
- graphEvents - Session graphs to show in session progress of different game indicators. This graph enables you to send a result for different timestamps during the session and visualize it in our Web Portal.
- Structure - graphEvents enables you to send up to 5 graphs. Each graph has a name and a list of event items which holds information regarding each timestamp. For example: {"graphEvents":{"Speed":[{"UTCTime":1561626805775.99,"index":0,"Result":3},{"UTCTime":1561626805892.99,"index":1,"Result":7}]. The index in the structure is an incremental index for each timestamp.
- Limitation - you will be able to send up to 5 graphs, the graph name can be up to 20 characters, event format must to be UTCTime,index,Result
- JSON example:
{ "calculatedData": [ { "name": "Score", "value": "360", "unit": "" }, { "name": "Speed", "value": "12", "unit": "m/s" }, { "name": "Success", "value": "98", "unit": "%" } ], "graphEvents": { "Speed": [ { "UTCTime": 1561626805775.99, "index": "0", "Result": 3 }, { "UTCTime": 1561626805892.99, "index": "1", "Result": 7 }, { "UTCTime": 1561626806758.99, "index": "2", "Result": 10 } ], "Accuracy": [ { "UTCTime": 1561626805775.99, "index": "0", "Result": 3 }, { "UTCTime": 1561626805892.99, "index": "1", "Result": 7 }, { "UTCTime": 1561626806758.99, "index": "2", "Result": 10 } ], "Efficiency": [ { "UTCTime": 1561626805775.99, "index": "0", "Result": 3 }, { "UTCTime": 1561626805892.99, "index": "1", "Result": 7 }, { "UTCTime": 1561626806758.99, "index": "2", "Result": 10 } ] } }
- UI view example:
resultData should be a JSON and consist of two parts - calculatedData and graphEvents.
calculatedData will contain data for general statistics (upper screenshot) and you will be able to send up to 5 calculatedData results, and for each item the "name" value can be up to 25 characters, the sum of "value" and "unit" up to 12 characters.
graphEvents will contain data for graphs (lower screenshot) and you will be able to send up to 5 graphs data, the graph name can be up to 20 characters.Response
-
Code: 200and JSON with ID of saved session:
{ "id": 1111 }
Errors
-
Code: 401Returned when user token was expired or invalid
{ "code": 0, "message": "string" }
-
Code: 403Returned when user has not access to this action
{ "code": 0, "message": "string" }
-
Code: 409Returned when request data invalid or empty
{ "code": 0, "message": "string" }
-
Code: 500Returned when something happened wrong on the server side
{ "code": 0, "message": "string" }
Curl request example:curl -X POST "https://api.portal.consumer-dev.xr.health/api/developer/workout-sessions" \ -H "Content-type:\ application/x-www-form-urlencoded" \ -H "Authorization:\ Bearer\ accessToken" \ -d "duration=75" \ -d "epocStartTime=1561626806758" \ -d "score=5600" \ -d "levelPlannedParams={\"SpeedLevel\":+\"0\",\"SessionDuration\":+\"8\",\"Difficulty\":+\"Basic\",\"GameMode\":+\"Enabled\"}" \ -d "softwareVersion=1.1.0" \ -d "resultData={\"calculatedData\":+[{\"name\":+\"Score\",\"value\":+\"360\",\"unit\":+\"\"}],\"graphEvents\":+{\"Speed\":+[{\"UTCTime\":+1561626805892.99,\"index\":+\"1\",\"Result\":+7}],\"Accuracy\":+[{\"UTCTime\":+1561626805775.99,\"index\":+\"0\",\"Result\":+3}],\"Efficiency\":+[{\"UTCTime\":+1561626805775.99,\"index\":+\"0\",\"Result\":+3}]}}"
How to get List of saved Workout Sessions.
For getting saved Workout Sessions use GET https://api.portal.consumer-dev.xr.health/api/developer/workout-sessions endpoint with:
Headers
-
Content-typerequiredapplication/x-www-form-urlencoded
-
AuthorizationrequiredBearer access token
Parameters
-
limitoptionalDefault: 10Number of limit records.
-
pageoptionalDefault: 1Current page for pagination.
-
orderoptional. Default: DESCOrder by
Response
-
Code: 200and JSON with:
{ "sessions": [ { "id": 1111, "duration": 75, "levelPlannedParams": "{}", "resultsData": "{}", "softwareVersion": "1.1.0", "epocStarttime": "1561626806758", "score": 5600 } ], "total": 1 }
Errors
-
Code: 401Returned when user token was expired or invalid
{ "code": 0, "message": "string" }
-
Code: 403Returned when user has not access to this action
{ "code": 0, "message": "string" }
-
Code: 500Returned when something happened wrong on the server side
{ "code": 0, "message": "string" }
Curl request example:curl -X GET "https://api.portal.consumer-dev.xr.health/api/developer/workout-sessions?limit=1&page=1&order=DESC" \ -H "Content-type:\ application/x-www-form-urlencoded" \ -H "Authorization:\ Bearer\ accessToken"
How to validate oauth token.
For validate token use GET https://api.portal.consumer-dev.xr.health/api/sandbox/oauth/token/validate/{token} endpoint with:
Headers
-
Content-typerequiredapplication/x-www-form-urlencoded
Parameters
-
tokenrequired
Response
-
Code: 200and JSON with:
{ "valid": true, "message": "" }
-
Code: 200and JSON with:
{ "valid": false, "message": "User is already connected from a different device or invalid." }
Errors
-
Code: 500Returned when something happened wrong on the server side
{ "code": 0, "message": "string" }
Curl request example:curl -X GET "http://127.0.0.1:8000/api/sandbox/oauth/token/validate/MmFmMDA4OGRiMzUxZmQ0NmRjMGNmYmZiOGFkMmM3MTcxM2IyYjRiMjYyMzBkODk5MjU4YjhmMGQwMWNjNmY5ZQ" -H "accept: application/json"