ARIA API II: ARIA API Resources
- mschmidt33
- Jun 22
- 11 min read
Introduction
In our previous article, ARIA API I: HL7, FHIR, and the ARIA API, we explored the foundations of interoperability in healthcare and radiation oncology. We discussed how HL7 developed the FHIR standard to simplify healthcare data exchange and how Varian has adopted these modern interoperability standards through the ARIA API platform.
Understanding the concepts behind FHIR and the ARIA API is an important first step, but eventually every developer relies on the specifications of the API to build clinical tools. Fortunately, Varian provides several resources that make discovering and testing ARIA API functionality straightforward. Two of the most valuable tools available to developers are:
The ARIA API Specifications Page
The ARIA API Tester
Together, these resources provide a roadmap for exploring available endpoints, understanding the structure of FHIR resources, and validating requests before writing production code.
In this article, we will explore both tools and demonstrate how they can accelerate development of ARIA-integrated applications.
ARIA API Specifications Page
The ARIA API Specifications Page serves as the primary reference manual for the ARIA API ecosystem. If you have ever worked with APIs that provide Swagger or OpenAPI documentation, the experience will feel familiar. The specifications page acts as an interactive catalog of all supported resources, operations, request parameters, and response structures available through the platform. For new developers, the specifications page is a primary resource when determining whether a particular piece of information can be accessed through the API and which profiles are read-only and which profiles can modify patient data.
For new developers, the specifications page is a primary resource when determining whether a particular piece of information can be accessed through the API and which profiles are read-only and which profiles can modify patient data.
The first section many developers encounter within the ARIA API Specifications is the Profiles page. In FHIR terminology, a profile is a specialized implementation of a standard FHIR resource. While HL7 defines generic healthcare resources such as Patient, Appointment, Observation, and ServiceRequest, software vendors often extend or constrain these resources to better represent their clinical workflows. The Profiles page documents these implementations and serves as an entry point for understanding the data available within ARIA.
The resources are organized into several major domains:
Domain | Description | Examples |
Foundation | Contains resources that support the overall operation of the API Ecosystem. |
|
Base | Contains core entities that most applications interact with regularly. |
|
Clinical Resources | Resources most relevant to radiation oncology workflows. Includes specific radiotherapy specific profiles. |
|
Financial | Resources associated with billing and charge management. |
|
Content
It may be most useful to dive into a single profile to describe the resources within. On selecting a profile multiple tabs at the top allow the reader to dive into different aspects of the profile. The first tab at the top is Content where the official description of the profile exists. For this example, the Patient profile shows the following information under the Content of the profile.
Differential Table - highlights how the ARIA profile differs from the underlying FHIR base resource.
Key Elements Table - provides a simplified view of the most important fields of the profile.
Snapshot Table - provides complete definition of the profile after all constraints and inheritance have been applied.
Statistics/References Table - Additional metadata about the profile.
Looking closely at one of these tables, the Key Elements Table, we can identify the properties of the table that may be of interest.
From this table, we can see the headers described at the top: Name, Flags, Cardinality, Type, and Description & Constraints. The layout of the table look different than what developers might be familiar with from the ESAPI Online help file or from github descriptions of class libraries. Below is a help guide for how to read this type of table.
Many of these properties are hyperlinks to a more Detailed Description of the property or value. For instance, from the image of the Key Elements Table above, clicking on the link uSCoreEthnicity the description of the property opens in the browser. Utilization of the Detailed Description hyperlink has been helpful in determining the written rules behind strongly structured data such as the type in the document-reference profile or the status in the appointment profile.
Operations and Search Parameters
While the Profile, Key Elements, and Snapshot views help developers understand the structure of a resource, the Operations and Search Parameters tabs explain how the resource can actually be used within the ARIA API. These tabs are a first place to look to describe how a resource can be used or what search parameters can be used to find a specific resource. Using the Appointment Resource as an example, please see the Operations accessible for radiotherapy appointments.
Operation | Method | Description |
Create | POST | Create a new appointment |
Update | PUT | Update an existing appointment |
Read | GET | Retrieve a specific appointment |
Search | GET | Search for appointments |
$checkin | POST | Check a patient into an appointment |
$checkout | POST | Check a patient out of an appointment. |
The Search Parameters tab is equally important because it documents the fields that can be used to filter and retrieve resources.
Name | Type | Description |
_id | token | The ID of the resource |
_lastUpdated | date | Last updated date time of the resource |
actor | reference | Any one of the individuals participating in the appointment |
date | date | Appointment date/time |
identifier | token | The Identifier of the Appointment |
patient | reference | One of the individuals of the appointment is this patient. |
reminder-date | date | Prior reminder DateTime of the appointment |
service-category | token | A broad categorization of the service that is to be performed during this appointment |
service-type | token | The specific service that is being performed during this appointment. |
status | token | The overall status of the appointment. |
How to
The How to tab header contains the following links to assist in the specification.
VAIS Token Generation | Describes how VAIS token web service can be used to access FHIR resources. This article shows how to utilize Postman to generate a VAIS token, and also shares important information such as where the token can be acquired (e.g., https://hostname:44333/tokenservice/connect/token) |
VAIS Operation Scopes | Shows scopes and rights required for each operation to be used. Also defines the required user rights of the VAIS client to perform actions on patient objects in ARIA. |
VAIS Client Creation | Describes how to create a VAIS client. This is a step-by-step guide that is more concise than the prior blog post that also describes how to generate a VAIS client. |
Radiotherapy | Describes how radiotherapy (RT) data is exposed from ARIA in FHIR format. |
Valueset and Code System List | Provides a comprehensive list of all ARIA API Valuesets, including their respective Code System Details. |
The how-to guides have obvious utilities for those getting started with ARIA API, but a couple of other hidden gems exist in this section.
Radiotherapy
While the Specifications page describes the available resources and their structure, the Radiotherapy section explains how familiar ARIA treatment planning concepts are represented using standardized FHIR resources. This documentation is particularly important because the ARIA API follows the CodeX Radiation Therapy (RT) Implementation Guide and mCODE (minimal Common Oncology Data Elements) standards. These standards provide a consistent way to exchange radiation oncology information between systems while maintaining interoperability across vendors.
For developers familiar with Eclipse Scripting API (ESAPI) or ARIA database concepts, this section serves as a translation guide between the ARIA data model and the FHIR representation exposed through the ARIA API. One of the most important concepts in the ARIA API radiotherapy model is understanding the difference between ServiceRequest resources and Procedure resources.
ServiceRequest describe what was prescribed or planned.
Procedure describe what was actually delivered.
ValueSet and Code System List
Another extremely valuable resource within the ARIA API documentation is the ValueSet and Code System List. At first glance, this page may appear to be little more than a reference table. In reality, it provides developers with one of the most important tools for building robust and maintainable applications. First, let's briefly define ValueSet and Code System.
ValueSet - defines the list of valid values that may be used for a particular field.
Code System - defines the actual codes and meanings associated with those values.
A future blog post is planned to go over useful code snippets and practical examples, but this blog will share one now to drive home the value of this list. One of the most practical uses of the ValueSet and Code System documentation came during the development of an application that automatically uploads documents into ARIA using the DocumentReference resource.
When creating a DocumentReference, the resource requires a valid document type to be specified. This value ultimately populates the DocumentReference.type field and must correspond to one of the document types configured within ARIA (i.e. Consent, Treatment Plan Report, Basic Dose Calculation, etc.). However, the ARIA API expects the associated code from the configured document type ValueSet. Without the correct code, the document cannot be categorized properly within ARIA.
Fortunately, the ValueSet and Code System documentation identifies that document types are defined by the ValueSet:
Using this information, we can dynamically query ARIA to retrieve all currently configured document types rather than hardcoding values into our application.
The following method performs a ValueSet expansion request and extracts the available document type codes and display names:
private static Dictionary<string, string> GetValidDocumentTypes(
string baseUrl,
HttpClient client,
string publisher)
{
var documentTypes = new Dictionary<string, string>();
try
{
string valueSetUrl =
$"{baseUrl}/ValueSet/$expand?url=http://varian.com/fhir/ValueSet/documentreference-type&publisher={publisher}";
Console.WriteLine($"Querying: {valueSetUrl}");
var response = client.GetAsync(valueSetUrl);
var result = response.Result.Content.ReadAsStringAsync().Result;
if (response.Result.IsSuccessStatusCode)
{
var valueSetJson = JObject.Parse(result);
foreach (var entry in valueSetJson["entry"])
{
var expansion = entry["resource"]["expansion"];
if (expansion != null && expansion["contains"] != null)
{
foreach (var item in expansion["contains"])
{
documentTypes.Add(
item["code"]?.ToString(),
item["display"]?.ToString());
}
}
}
}
else
{
Console.WriteLine(
$"Warning: Could not fetch document types. Status: {response.Result.StatusCode}");
}
}
catch (Exception ex)
{
Console.WriteLine(
$"Warning: Error fetching document types: {ex.Message}");
}
return documentTypes;
}After retrieving the available document types, we can locate the code associated with a particular display name. For example, the code calling this method can find the returned key with a value of "Treatment Plan Report". The resulting code can then be used when constructing the DocumentReference resource:
var docRef = new DocumentReference
{
Status = "current",
DocStatus = "final",
Subject = new Reference
{
ReferenceValue = $"Patient/{patientFhirId}"
},
Date = DateTime.UtcNow.ToString("yyyy-MM-ddTHH:mm:ss.fffZ"),
Description = fileName,
Type = new CodeableConcept
{
Coding = new List<Coding>
{
new Coding {
System = "http://varian.com/fhir/CodeSystem/documentreference-type",
Code = docCode,
Display = documentType
}
}
}
}... code goes on to set other properties.In this example, the ValueSet documentation served as the starting point for discovering the correct API endpoint and Code System required to populate the DocumentReference.type field. Rather than hardcoding assumptions about valid document types, the application retrieves the configured values directly from ARIA and uses the corresponding code when creating the resource.
Examples
The final section header discussed in this blog post will be the Examples. Examples allow developers to understand some of the FHIR profile behavior directly from the code. One example to look at is the BodyStructure example.
Selecting an example, in this case Radiotherapy Volume Example, shows the example page where the example can be viewed in either XML or JSON. Viewing the JSON formatted code, the following starts the file:
{
"resourceType": "BodyStructure",
"id": "BodyStructure-PV-681",
"meta":
{
...
}
}The resourceType identifies the FHIR resource being represented, while the meta section contains important metadata about the resource, including the profiles it conforms to. The profile section beneath shows the resources in mCODE and CodeX RT for which this response is compliant.
Also useful, extensions for the reference point details Eclipse users are accustomed to leveraging in ARIA are detailed. The extension mechanism allows vendors to add radiation oncology-specific information while remaining compliant with the FHIR standard. These are not natively part of the BodyStructure resource, but extensions allow it to be available through the Varian radiotherapy profile. See below the extension for the daily-dose-limit.
"extension": [
{
"url": "http://varian.com/fhir/v1/StructureDefinition/daily-dose-limit",
"valueQuantity": {
"value": 10000.0,
"code": "cGy"
}
},...ARIA API Tester
While the Specifications page provides the roadmap to the ARIA API, the ARIA API Tester provides a hands-on environment for exploring and interacting with the API itself. Rather than simply reading documentation, developers can use the API Tester to execute requests, inspect responses, and experiment with resources in real time.
The API Tester is particularly useful when learning a new resource. Instead of building a C# application to retrieve patients, appointments, prescriptions, or treatment plans, developers can first execute the query directly within the tester and immediately inspect the results. The returned JSON can then be used as a blueprint when implementing the same request in code.
In this section, a simple request to retrieve the patient _id parameter will then be leveraged to identify appointments associated with this patient. As with the previous blog post, our first step is to generate a token within the tool by importing the Client ID, Client Secret, and Scope into the VAIS Token section and select Generate Token.
Once the token has been generated, navigate on the left navigation panel to the Patient Resource on the left navigation panel of the page. The patient MRN in ARIA is not the patient _id but rather one of the many patient identifier properties. In the Search Parameters area, change the initial dropdown to identifier - Supports 'AND' search with listOr param for the... On this selection, the search parameter allows the user to input either a System or a Code. The Code in this example is where the patient MRN should be input. The System can be thought of as a namespace of where the identifier originates (in this example a patient MRN is in system ARIAID1).
Using the response we can find the id of the patient resource representing our patient RapidPlan-01.
Now that we know the resource id of the patient, the Appointment resources can be collected. Select the Appointment Resource in the left hand navigation window. In the search parameter, select the Patient parameter and update with the patient id-- Patient-437 in this case. Note: other useful parameters exist for searching with appointments as described in the sections above, such as date, status, etc. This patient does not have so many appointments in the test database, and all can be searched if the search parameters are left blank.
After clicking Search, it is useful to examine how the Request is formatted with the search parameter. The following structure is noted for GET Requests:
This request returns a Bundle that consists of the first 10 out of 29 appointment record entries. The first page here showing the first 10 entries. This is not a consequence of the API test page, but the ARIA API resource also limits the response to a specific amount within a page. In the next blog post as we go through similar examples using C# code, we will explore how to identify and access multiple page responses, but in the API tester, the next page can be accessed with a push of a button.
Beneath the Bundle summary, the individual Appointment resource entries are displayed. This allows users to quickly identify useful fields such as appointment status, scheduled start and end times, participating providers, locations, and references to the associated patient.
Understanding the distinction between the Bundle and the individual resources is an important FHIR concept that appears throughout the ARIA API. Nearly all search operations return Bundles, while individual resources are typically returned when performing a direct Read operation against a specific resource identifier.
Conclusion
The ARIA API represents a significant shift from traditional approaches to accessing radiation oncology data. Rather than relying on direct database access, custom integrations, or proprietary interfaces, developers are provided with a modern, standards-based platform built on FHIR, mCODE, and CodeX RT.
Fortunately, developers are not expected to learn every resource, profile, ValueSet, or operation from memory. As we have explored throughout this article, the ARIA API Specifications Page and API Tester provide a rich set of tools for discovering available resources, understanding their structure, identifying supported operations, and validating requests before writing a single line of code.
The Specifications Page serves as a roadmap to the API ecosystem. Whether investigating radiotherapy-specific profiles, reviewing search parameters, understanding ServiceRequest versus Procedure resources, exploring ValueSets, or examining complete example resources, the documentation provides a tremendous amount of information that can accelerate development and reduce frustration.
Likewise, the API Tester allows developers to interact directly with the API, inspect real responses, experiment with search parameters, and better understand how resources relate to one another. By using the tester to explore requests and responses before writing code, developers can often identify solutions in minutes that might otherwise take hours of debugging.
In the next article, we will build upon the concepts introduced here and begin interacting with the ARIA API programmatically using C#. We will cover authentication, executing requests with HttpClient, handling paginated Bundle responses, parsing resources, and translating many of the examples from this article into reusable code. By combining the documentation, API Tester, and a few practical coding patterns, developers can rapidly begin building applications that leverage the full capabilities of the ARIA API.
Comments