onyxOS API Documentation

Background

When CMS issued the Interoperability and Patient Access Rule in May 2020 they provided guidance that adopting a set of HL7 Implementation Guides (IG) would enable the payers that are covered by the rule to achieve compliance. The Relevant implementation Guides are:

• CARIN Consumer Directed Payer Data Exchange (CARIN IG for Blue Button®) 1.1.0 - STU1
• Da Vinci Payer Data Exchange -1.0.0 STU1
• HL7 FHIR® US Core Implementation Guide STU3 Release 3.1.1
• DaVinci Payer Data Exchange (PDex) US Drug Formulary - 1.0.1 STU1
• DaVinci PDex Plan Net - 1.0.0 STU1
• DaVinci Payer Data Exchange US Drug Formulary STU2.0.1
• SMART App Launch Framework IG R1.0

The Payer Data Exchange (PDex) IG incorporates the data profiles defined in the US Core 3.1.1 IG.

The PDex Plan-Net IG differs from the other IGs in that it does not require member authentication and authorization in order to access the API. Plan-Net is an Open API.

Accessing the APIs

The Patient Access APIs require that each application has a set of app credentials. These credentials are used in an OAuth2.0/SMART-on-FHIR access authorization flow that enables the individual member to grant a registered app to access their data.

To register an app Developers can go to the Developer Portal.

onyxOS, the Interoperability Rule and FHIR Implementation Guides

onyxOS has been designed to convert FHIR Implementation Guides into APIs. onyxOS can ingest a capability statement and create the required APIs together with the relevant member-level access controls.

In order to comply with the CMS Interoperability Rule we provide access to the following resources to support developers who are creating applications that make use of the IGs identified in the previous section.

• Implementation Guides
• Capability Statements
• Swagger Files
• Postman Collections

Implementation Guides

For developers who are not familiar with HL7 FHIR Implementation Guides (IGs). An IG provides detailed information on data structures for resource profiles. It also provides information on Search parameters and other technical aspects of the use cases that the IG was designed to address. Each IG builds on the base FHIR Release 4 specification for elements such as, field definitions and data types.

You are strongly encouraged to refer to the introductory sections of each IG. The introduction will provide a context to the use cases the guide addresses. This can have implications for how the information is accessed and the type of searches that are supported.

The links to each guide are provided below:

• CARIN Consumer Directed Payer Data Exchange (CARIN IG for Blue Button®) 1.0.0 - STU1
• Da Vinci Payer Data Exchange -1.0.0 STU1
• HL7 FHIR® US Core Implementation Guide STU3 Release 3.1.1
• DaVinci Payer Data Exchange (PDex) US Drug Formulary - 1.0.1 STU1
• DaVinci PDex Plan Net - 1.0.0 STU1
• DaVinci Payer Data Exchange US Drug Formulary STU2.0.1 {:target=”_blank”}
• SMART App Launch Framework IG R1.0

Capability Statements

Server Capability Statements define the data profiles, operations, access methods and search operations that are supported by the server.

The Capability Statement can be referenced using the [base_url][/ig_name]/metadata endpoint.

When working with different client instances of onyxOS, the content of the capability statements will be the same with just the [base_url] value changing to point to a different environment.

Swagger Files

onyxOS creates OpenAPI.json files, frequently referred to as swagger files from the Capability Statements provided. The swagger files enable developers to better understand the server interactions.

Swagger files are available for download using the same endpoint conventions as for capability statements. Therefore, if a Capability Statement is at:

• [base_url][/ig_name]/metadata

The openapi.json file will be found at:

• [base_url][/ig_name]/openapi.json

onyxOS also provides a swagger UI for each openapi.json file. the links for the appropriate IGs are as follows:

Postman Collections

Postman is a popular API tool used by Developers. The Onyx Development team have provided a set of Postman collections to accelerate development of apps that use the FHIR APIs published by the SAFHIR platform.

[]: