Testing OneRecord API

Testing your integration with OneRecord API is a critical step in ensuring that your solution can securely and reliably retrieve healthcare data from OneRecord's network. OneRecord recommends different levels of testing to help you prepare and validate your integration, from exploring the API capabilities to testing with your own account's sandbox API Access Token(s). By following these testing steps, you can ensure that your application is properly configured and can handle patient data in a compliant and secure way.

Test Access

When trying the API, use the global sandbox API Access Token with OneRecord API Reference, which is limited to healthcare data for a test patient supplied by OneRecord.

When Testing the API, use your Tenant's sandbox API Access Token in OneRecord API Reference or with OneRecord API's Postman Collection. The collection can be used from the browser directly, or use the orange "Run In Postman" button, which allows using your Postman installed natively.

When Integrating the API, make API calls from your own solution's codebase using your Tenant's sandbox API Access Tokens(s) in your development environment. In pre-production and production, you will use your Tenant's live API Access Token, which are provided after certification is passed and your account is securely configured by OneRecord to the networks.

📘

Important to Note

Your Tenant's API Access Tokens should be stored securely in a secrets vault or equivalent. Checking OneRecord API Access Token into source control as environment variables and uploading to the internet is in conflict with OneRecord's recommended security protocol.

Environments

OneRecord API offers three environments for API calls: Stage, Pre-Production, and Production, each with a different URL. To test the API, use the stage URL with your sandbox API Access Token. To make API calls in pre-production or production, use the appropriate URL with your live API Access Token.

To use OneRecord API, solutions call the API's microservices directly until OneRecord is able to maintain a central gateway in the future. This requires an understanding of which services to call and in what order to achieve the desired flow of fetching data. The developer documentation provides guides for identifying the necessary services and endpoints for your solution.

The main services used in OneRecord API are the Directory Service and the Integrator Service. The URLs for each environment are as follows:

Directory service:

• Stage URL: https://stage.directory.onerecord.com
• Pre-Production URL: https://pre.directory.onerecord.com
• Production URL: https://directory.onerecord.com

Integrator service:

• Stage URL: https://stage.integrator.onerecord.com
• Pre-Production URL: https://integrator-pre.onerecord.com
• Production URL: https://integrator.onerecord.com

Methods of Testing

There are various methods of testing OneRecord API depending on the level of testing and whether or not you have a test JWT token yet for your Tenant account.

If your account does not yet have a test JWT token, the API Reference is the best method of testing. The API Reference allows you to test OneRecord API calls directly through your web browser.

Once you have obtained a test JWT token for your Tenant account, it is recommended to use OneRecord's Postman Collection or the command line utility, Curl, to test API calls. OneRecord's Postman Collection is a convenient way to test API calls during the testing phase, while the command line utility Curl can be used to test API calls programmatically.

When you are ready to fetch real PHI data, API calls should be made directly from your application code using the appropriate sandbox or live API Access Token.

Test Data

OneRecord uses the same test patient information regardless of the interoperability standard or network being used. The test patient is configured as follows:

This test patient has records populated in FHIR, Commonwell, and Carequality, so regardless of which path you choose to test with OneRecord API, you should be able to retrieve records for this patient.

The patient demographics exist in the Commonwell directory, and the patient has credentials for the following FHIR endpoints:

Carequality does not have centralized network functionality that can be leveraged for testing. Therefore, you cannot request access for this patient in test mode from the Carequality directory. Instead, Carequality test responses contain data from a test patient in the OneRecord Consumer Hub.

Note that this test patient is only meant to be used for testing purposes, and OneRecord does not provide actual patient data when using your sandbox API Access Token.

HTTP Response Codes

OneRecord API returns standard HTTP response codes. All HTTP responses will contain a transaction id if a transaction was initiated, which can be used for tracking down the error in OneRecord's API logs. Some common HTTP response codes include:

All OneRecord API request errors return a body like this:

{
  "codes": [
    {
      "timestamp": "03-01-2022 14:33:58",
      "status": 500,
      "error": "Internal Server Error",
      "message": "<error message>"
    }
  ]
}