R4 and R6 Interoperability

Choose the DDFS FHIR version that supports your resource and workflow, and keep requests on the corresponding versioned API base path.

Overview

DDFS provides a FHIR R4 (4.0.1) API surface and a FHIR R6 ballot4 (6.0.0-ballot4) API surface. The API surfaces are version-specific; a resource created on one surface is addressed through that same versioned base path.

Use the CapabilityStatement returned by the metadata endpoint for the deployed DDFS instance as the authority for the resources, interactions, operations, formats, and search parameters that the instance advertises. Check it during integration setup and after a service update.

The examples use these placeholders for the version-specific FHIR API base URLs:

{r4-api-base}: https://<ddfs-instance-id>.ddfs.<region>.oci.oraclecloud.com/api/fhir/r4
{r6-api-base}: https://<ddfs-instance-id>.ddfs.<region>.oci.oraclecloud.com/api/fhir/r6-ballot4

The metadata endpoints allow anonymous requests. No access token or Authorization header is required.

GET {r4-api-base}/metadata
Accept: application/fhir+json

GET {r6-api-base}/metadata
Accept: application/fhir+json

Interoperability Model

A client checks the capability statement, chooses the matching versioned base path, and uses only the capabilities advertised for that version. Shared client logic can handle common FHIR response forms, including Bundle search results, OperationOutcome errors, and application/fhir+json content.

Key Differences

Base path: R4 requests use /api/fhir/r4. R6 requests use /api/fhir/r6-ballot4.
FHIR release: The R4 surface uses FHIR R4 (4.0.1). The R6 surface uses FHIR R6 ballot4 (6.0.0-ballot4).
Resource coverage: Review FHIR R4 Resources and FHIR R6 Resources, and then confirm the deployed capability statement.
R6 workflows: Resources such as DeviceAssociation, Subscription, and SubscriptionTopic are documented on the R6 API surface.
Search behavior: Parameter, comparator, modifier, chain, include, and reverse-include support can differ by resource and version.

Find the Correct Base Path for the DDFS Instance

1. Open the navigation menu, select Developer Services, and then select Device Data FHIR Service.
2. On the DDFS Instances list page, select the instance that you want to work with.
3. On the instance details page, find Developer Integration.
4. Copy the R4 FHIR API base URL or R6 FHIR API base URL required by your workflow.
Use this command and the required parameters to get information about a DDFS instance:
```
oci ddfs instance get --instance-id <instance-OCID>
```
Use the returned FHIR service endpoint with the R4 or R6 ballot4 version path shown in the Overview.

For a complete list of parameters and values for this CLI command, see CLI Command Reference.
Run the GetInstance operation to get information about a DDFS instance.

Use the returned FHIR service endpoint with the R4 or R6 ballot4 version path shown in the Overview.
1. Call GET {r4-api-base}/metadata or GET {r6-api-base}/metadata for the version under consideration.
2. Find the required resource in CapabilityStatement.rest.resource.
3. Confirm the required interaction, operation, format, and search parameters in that resource entry.
4. Send the resource request to the same versioned base path as the metadata request.
5. Keep the selected version in client configuration so that a version change is deliberate and testable.
If a needed capability is not advertised, do not infer it from another FHIR version. Select a documented alternative workflow or contact your DDFS administrator.

Examples

The following examples retrieve both capability statements and compare their advertised resource types. Metadata requests do not require an access token or Authorization header. The protected Patient search request in the curl example requires an OAuth 2.0 bearer access token with Patient search permission. When configuring the client grant and token request, use ddfssystem/Patient.s for search-only access or ddfssystem/Patient.rs for Patient read and search access.

Authorization and Errors

Metadata requests do not require authorization. For protected FHIR resource requests, use an OAuth 2.0 bearer access token issued by OCI Identity Domains. SMART on FHIR authentication and launch workflows are not supported.
For OAuth client setup, see Create Integrated Applications for DDFS OAuth. For scope guidance, see DDFS Authentication Reference.
Handle FHIR-formatted errors as OperationOutcome resources. See OperationOutcome Reference.

References

Retrieve the FHIR R4 (4.0.1) capability statement:

curl -sS -H "Accept: application/fhir+json" \
  "{r4-api-base}/metadata"

Retrieve the FHIR R6 ballot4 (6.0.0-ballot4) capability statement:

curl -sS -H "Accept: application/fhir+json" \
  "{r6-api-base}/metadata"

After confirming support, send the request to the corresponding API surface:

curl -sS -H "Authorization: Bearer <access-token>" \
  -H "Accept: application/fhir+json" \
  "{r4-api-base}/Patient?identifier=http%3A%2F%2Fhospital.example.org%2Fmrn%7C123456"

Retrieve the capability statements and list the resources advertised by each version:

$metadataHeaders = @{
  Accept = "application/fhir+json"
}
$r4 = Invoke-RestMethod -Headers $metadataHeaders -Method Get -Uri "{r4-api-base}/metadata"
$r6 = Invoke-RestMethod -Headers $metadataHeaders -Method Get -Uri "{r6-api-base}/metadata"

$r4.rest.resource.type | Sort-Object
$r6.rest.resource.type | Sort-Object

Check whether a resource is advertised on either surface:

$resource = "Subscription"
[pscustomobject]@{
  Resource = $resource
  R4 = $r4.rest.resource.type -contains $resource
  R6 = $r6.rest.resource.type -contains $resource
}

Oracle Cloud Infrastructure Documentation