Skip to content

FHIR Servers ​

Configure upstream FHIR servers that the proxy routes requests to. Each registered server gets a proxy path at /proxy-smart-backend/{server_name}/{fhir_version}/.

API Endpoints ​

Public discovery, readable without an admin token:

MethodPathDescription
GET/fhir-servers/List all registered FHIR servers
GET/fhir-servers/:server_idGet server details + proxy URLs

Admin routes, for admins and auditors (PATCH /admin/fhir-servers/:server_id/mcp is deprecated and removed in 0.9.0):

MethodPathSummary
GET/admin/fhir-servers/List FHIR Servers (admin)
POST/admin/fhir-servers/Add New FHIR Server
GET/admin/fhir-servers/:server_idGet FHIR Server (admin)
PUT/admin/fhir-servers/:server_idUpdate FHIR Server
DELETE/admin/fhir-servers/:server_idDelete FHIR Server
PATCH/admin/fhir-servers/:server_id/mcpToggle MCP Endpoint (deprecated)
GET/admin/fhir-servers/:server_id/mtlsGet mTLS Configuration
PUT/admin/fhir-servers/:server_id/mtlsUpdate mTLS Configuration
POST/admin/fhir-servers/:server_id/mtls/certificatesUpload Certificate
POST/admin/fhir-servers/:server_id/refreshRefresh FHIR Server Metadata
PATCH/admin/fhir-servers/:server_id/strict-capabilitiesToggle Strict Capability Enforcement

mTLS Configuration ​

For servers that require mutual TLS (client certificates), the /mtls routes above read the configuration, enable or disable it, and upload the client certificate.

Adding a Server ​

Fields:

  • Base URL (required) -- upstream FHIR server endpoint (e.g., http://hapi-fhir:8080/fhir)
  • Name (optional) -- what clients are told the server is called

On creation, the backend fetches the server's CapabilityStatement to discover its FHIR version and supported resources and operations. The server_name in proxy URLs is derived from the software name the server reports (e.g., hapi-fhir-server) and does not change when you rename the server. If an upstream from FHIR_SERVER_BASE is unreachable when the proxy starts, the server is listed under a name taken from its host until it answers; the first request for its usual server_name after that re-reads its metadata and puts it back under that name. A server whose settings were saved keeps the name they were saved under throughout.

Public Name ​

The proxy serves each server's CapabilityStatement with software.name set to the deployment's brand name (BRAND_NAME) and implementation.description set to the server's public name, which is the name an admin gave it or FHIR Server without one. The same public name is used in the user-access brand bundle (/branding.json) and on the instance page. A metadata refresh keeps the name an admin chose.

Proxy URL Structure ​

Once registered, the server is accessible through the proxy at:

/{backend-name}/{server_name}/{fhir_version}/{resource}

Example: /proxy-smart-backend/hapi-fhir/R4/Patient/123

All requests through the proxy pass through the authorization pipeline (token validation, scope enforcement, consent checks).

Strict Capabilities ​

When enabled, the proxy rejects requests for resources or interactions not declared in the server's CapabilityStatement. Toggle via PATCH /admin/fhir-servers/:server_id/strict-capabilities.

DICOM Servers ​

PACS/DICOMweb servers are managed separately:

MethodPathDescription
GET/admin/dicom-servers/List DICOM servers
POST/admin/dicom-servers/Add DICOM server
GET/admin/dicom-servers/:server_idGet details
PUT/admin/dicom-servers/:server_idUpdate
DELETE/admin/dicom-servers/:server_idRemove
GET/admin/dicom-servers/:server_id/statusProbe reachability
GET/admin/dicom-servers/viewer-appGet configured viewer app (any enabled registered SMART app, or one bundled with the proxy)
PUT/admin/dicom-servers/viewer-appSet viewer app
  • FHIR Proxy -- the request pipeline that processes proxied requests
  • SMART Apps -- apps that access FHIR servers through the proxy
  • Scope Management -- scopes enforced at the proxy layer
  • Monitoring -- server availability, response times, and the audit trail

Proxy Smart — Healthcare Interoperability Platform