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: Overall process

  1. 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"
}
  2. The "server_url" will be used for the POST API call.
  3. 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.
  4. 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-type
    required
    application/x-www-form-urlencoded or application/json
  • Authorization
    required
    Bearer access token
Parameters
  • duration
    required
    Workout session duration in seconds.
  • epocStartTime
    required
    Creation time in timestamp (milliseconds).
  • score
    required
    A score of the new session.
  • levelPlannedParams
    required
    JSON with workout session game settings.
  • softwareVersion
    required
    String provided by 3rd party developer to indicate 3rd party version number.
  • resultData
    required
    JSON 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:
      Level Planned Params
  • 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"
}
      • UI view example:
        Calculated Data
    • 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:
        Graph Events
  • 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: 200
    and JSON with ID of saved session:
    { "id": 1111 }
Errors
  • Code: 401
    Returned when user token was expired or invalid
    { "code": 0, "message": "string" }
  • Code: 403
    Returned when user has not access to this action
    { "code": 0, "message": "string" }
  • Code: 409
    Returned when request data invalid or empty
    { "code": 0, "message": "string" }
  • Code: 500
    Returned 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-type
    required
    application/x-www-form-urlencoded
  • Authorization
    required
    Bearer access token
Parameters
  • limit
    optionalDefault: 10
    Number of limit records.
  • page
    optionalDefault: 1
    Current page for pagination.
  • order
    optional. Default: DESC
    Order by
Response
  • Code: 200
    and JSON with:
                                            
{
  "sessions": [
    {
      "id": 1111,
      "duration": 75,
      "levelPlannedParams": "{}",
      "resultsData": "{}",
      "softwareVersion": "1.1.0",
      "epocStarttime": "1561626806758",
      "score": 5600
    }
  ],
  "total": 1
}
Errors
  • Code: 401
    Returned when user token was expired or invalid
    { "code": 0, "message": "string" }
  • Code: 403
    Returned when user has not access to this action
    { "code": 0, "message": "string" }
  • Code: 500
    Returned 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-type
    required
    application/x-www-form-urlencoded
Parameters
  • token
    required
Response
  • Code: 200
    and JSON with:
    
{
    "valid": true,
    "message": ""
}
  • Code: 200
    and JSON with:
    
{
    "valid": false,
    "message": "User is already connected from a different device or invalid."
}
Errors
  • Code: 500
    Returned 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"