From Azure API for FHIR to Health Data Services: A Zero-Surprise Migration Runbook

A FHIR migration can pass a resource-count check and still fail clinically. The destination may contain the same number of Patient, Observation, MedicationRequest, and Encounter resources while historical versions have been flattened, references resolve differently, custom searches return a different cohort, or a SMART launch no longer supplies the patient and encounter context that a clinician-facing application expects. Those are not cosmetic differences. They can change what an application displays, what a user is allowed to see, or whether a downstream workflow makes a safe decision.

Microsoft's migration FAQ states that Azure API for FHIR retires on September 30, 2026, after which customers cannot create or manage accounts, access data through the portal or APIs, receive service updates, or obtain support for the retired service. New customer deployments have already been blocked since April 1, 2025. A separate deadline applies to the legacy SMART on FHIR proxy: Microsoft's proxy guidance says it retires on September 21, 2026 and applications that still depend on it report errors after that date.

Production success therefore means more than copying data. It means preserving approved FHIR meaning, version history, identifiers, references, authorization boundaries, launch context, search behavior, client workflows, auditability, and a recovery path. This runbook treats the move as a controlled service transition: map the estate, compare platform behavior, choose lift-and-shift or incremental copy, prepare the workspace and security boundary, migrate with explicit history scope, reconcile data and searches, cut applications over, test SMART authorization, observe clinical integrity, and decommission only when the evidence supports it.

Define the Retirement Scope and the Two September Deadlines

The retirement is a service boundary, not a suggestion to schedule a future upgrade. According to Microsoft's migration strategies guidance, Azure API for FHIR retires on September 30, 2026. The older service is distinct from the Azure Health Data Services workspace and its FHIR service. After retirement, the access and support consequences described in the FAQ apply even if an application binary, service principal, or DNS entry still points at the old endpoint.

Treat the SMART proxy cutoff as an independent workstream. A team can complete data migration before September 30 and still break a clinician-facing SMART application on September 21 if the app depends on the proxy's callback relay, audience assumptions, or launch-context handling. Conversely, moving a SMART app does not migrate the FHIR store. Maintain two acceptance dates, two owners, and two test packs.

The first governance artifact is a deadline and dependency register. It should distinguish vendor-documented facts from internal milestones. Do not use a generic 'Azure FHIR retirement' ticket that can be closed after the first green smoke test.

Use the API developer learning path only as role context for the API engineering skills involved. The migration itself is a healthcare interoperability and operational-risk exercise, not a general career tutorial.

Build a FHIR Estate, Data, and Application Dependency Map

Start with authoritative discovery. The source resource name in Azure is not the estate. The estate includes every client, user, service principal, app registration, pipeline, export job, analytics consumer, event dependency, secret, certificate, DNS alias, private endpoint, firewall rule, search parameter, and operational runbook that assumes the old endpoint or its behavior.

Inventory by business workflow as well as technology. A medication reconciliation screen, patient portal, quality-measure pipeline, billing export, research extract, clinical decision support integration, or interface-engine feed may touch the same FHIR service differently. One may care about current state, another about historical versions, and another about exact search ordering or bundle semantics. That difference determines migration acceptance criteria.

Inventory Servers, Tenants, Clients, Jobs, and Integrations

For each client, record how it discovers the FHIR endpoint and token issuer. Hard-coded endpoint strings are obvious. Less obvious are deployment variables, Key Vault secrets, API Management backends, reverse proxies, mobile app configuration, integration-engine channels, scheduled scripts, notebooks, and vendor-managed interfaces. Search source repositories and configuration stores for both the hostname and old audience values.

This is where the dependency-discovery discipline in the Azure Service Bus migration runbook transfers cleanly: enumerate runtime consumers, not just resources. For FHIR, add clinical workflow ownership and patient-safety impact to the normal dependency map.

• Capture every registered redirect URI and SMART launch URL, including non-production and vendor-owned callbacks.

• Capture all scheduled $export operations, storage destinations, retention policies, downstream loaders, and reconciliation jobs.

• Capture all custom SearchParameter resources and the jobs or scripts used to reindex them.

• Capture audit evidence obligations, including how long migration manifests, authorization results, and cutover approvals must be retained.

• Assign a business validator to every critical workflow. Technical ownership alone cannot sign off a clinician-visible result.

Compare Azure API for FHIR With the Health Data Services FHIR Service

Do not assume the successor is a drop-in endpoint replacement. Microsoft's FHIR service overview describes the target as a managed FHIR service inside Azure Health Data Services, with Microsoft Entra role-based access control, audit logging, and SMART on FHIR support. Microsoft's migration matrix also calls out differences in search capability, transaction bundles, events, autoscaling, disaster-recovery features, and data-ingress mechanisms.

The comparison should be workload-specific. A platform difference matters only when a client depends on it, but a dependency is often hidden until a negative test fails. Capability-statement comparison is necessary because clients may dynamically inspect the metadata endpoint, yet metadata parity is not sufficient. A client can see the same resource type and still receive a different result set for a chained search or custom parameter.

Use API-first design in transformation programs as background for contract ownership: treat endpoint, metadata, error, authorization, and search behavior as consumer-facing contracts. The FHIR-specific acceptance work remains in this runbook.

Select Lift-and-Shift or Incremental Copy by Downtime and Data Volume

Microsoft documents two broad patterns in its migration strategies. Lift-and-shift uses export followed by import and is the simpler choice when the source can tolerate a longer write outage. Incremental copy keeps the legacy service operating while data is moved in stages, reducing final downtime but increasing reconciliation complexity and the need to reason about deltas, versions, and concurrent change.

Choose by operational constraints, not by which tool looks easier in a proof of concept. The decision record should cover source write rate, historical-version scope, data volume, expected export and import duration, validation duration, permitted read and write downtime, number of clients, ability to freeze writes, and rollback design. If history must be preserved, import mode and input metadata become part of the architecture, not an implementation detail.

Escalate Large Stores and Capacity Constraints Early

Microsoft's guidance contains two important volume thresholds that should not be conflated. The target's current documented support is 4 TB, with a support request required for more than 4 TB. Separately, Microsoft says that if an Azure API for FHIR instance contains more than 2 TB, open a support request before starting migration and include both the source and target instance names. Treat the 2 TB threshold as a planning trigger, not as a target hard limit.

A useful support request includes the source size and growth trend, required historical scope, desired target region, expected migration pattern, permitted outage, staging-storage design, encryption/network restrictions, planned parallelism, test window, and the consequence if migration exceeds the planned window. For a target expected to exceed documented support, do not proceed on verbal assumptions. Record the supported path, capacity limits, and any Microsoft guidance in the change record.

• Stop before bulk migration if target capacity or support status is unresolved.

• Load-test representative resource sizes and search patterns before the production import window.

• Validate staging-storage throughput and network policy with real migration-format files, not only small samples.

• Reserve time for reconciliation and reindexing. Transfer completion is not the same as clinical readiness.

Prepare the Target Workspace, FHIR Service, Network, and Security Controls

Azure Health Data Services uses a workspace model. Microsoft's Azure Health Data Services overview distinguishes the workspace and its FHIR service from the older standalone Azure API for FHIR resource. Deploy the target through repeatable infrastructure so region, workspace, FHIR service, identities, encryption, logging, networking, policy, and tags can be recreated and reviewed consistently.

Network migration deserves its own test. A private endpoint that resolves from an administrator's workstation does not prove that an integration engine, private build agent, vendor network, or analytics worker can reach the target. Recreate DNS, routing, firewall, proxy, and private-access rules from the actual client subnets. Verify both intended access and denied paths.

Microsoft documents Private Link for Azure Health Data Services as a mechanism for restricting access. Treat it as one layer in the boundary: identity, role assignment, endpoint exposure, storage permissions, and logging still require explicit configuration and negative testing.

Rebuild Identity, RBAC, and Authority Assumptions

Authorization behavior is a migration surface. A resource that exists in the target but is newly visible to an unauthorized client is a migration failure. So is a legitimate client that can no longer obtain a usable token because its issuer, audience, role, or tenant assumptions were copied incorrectly.

Microsoft's migration guidance states that Azure Health Data Services FHIR service does not support Azure API for FHIR local RBAC and custom authority in the same way, and that the token issuer authority must be the authentication endpoint for the tenant in which the FHIR service runs. The older service guidance describes scenarios where Azure RBAC or local RBAC could be used. Do not translate those configurations one-for-one.

This is where the principles in secure and scalable API design are relevant: explicit authentication, authorization, validation, and least privilege. The healthcare-specific requirement is to prove that each approved FHIR operation is allowed and that every disallowed operation fails safely for the correct reason.

Replace Local RBAC and Custom Authority Dependencies

Build a permission matrix by actor and operation: read, search, create, update, conditional update, delete, history access, export, import, and administrative jobs. Run the tests with production-like identities, not a subscription owner. Include wrong-tenant, missing-role, expired-token, revoked-credential, and stale-group-membership cases.

• No production cutover while any critical client still depends on the legacy authority or local-RBAC behavior.

• No broad role assignment as a temporary migration shortcut unless it has a documented expiry and executive exception.

• No secret copied without confirming owner, rotation date, storage location, and revocation path.

• Every role migration must have both a positive test and a negative test.

Migrate Historical Data, Versions, and Referential Relationships

Decide what 'the data' means before moving it. FHIR current state, historical versions, soft-deleted resources, custom SearchParameter resources, provenance resources, audit logs, export artifacts, and downstream analytic copies are different objects with different migration behavior. The approved scope should list resource types and version-history requirements explicitly.

Microsoft's FHIR import documentation makes a critical distinction. Initial import is intended for an empty server, blocks API writes, retains only the latest version, and sets lastUpdated to import time. Incremental import can preserve versionId and lastUpdated when supplied in the input and can ingest multiple versions. If historical versions or original timestamps matter, an initial import by itself is not equivalent.

Preserve logical resource identifiers wherever the approved migration method allows, then validate references as graph edges, not strings. A MedicationRequest.subject reference that points to Patient/123 is only useful if Patient/123 exists, is the intended patient, and the calling application can resolve it under the target's authorization model. Include contained references, canonical references, version-specific references, and externally resolvable references in the test design.

If a resource cannot be imported cleanly, do not silently coerce it. Quarantine the record with source identifier, resource type, version, validation error, decision owner, remediation status, and whether the exception affects a critical workflow. That ledger becomes part of rollback and decommissioning evidence.

Validate $export, $import, Incremental Copy, and Reconciliation

Bulk movement should be restartable and auditable. The source Azure API for FHIR export guidance uses $export to write newline-delimited JSON (NDJSON) to configured Azure Storage. The target's import path reads NDJSON from configured Blob Storage or Azure Data Lake Storage Gen2. Microsoft's import configuration guidance requires appropriate FHIR and storage permissions and documents network-access options for the import path.

Create a migration ledger for every run. At minimum record run ID, source watermark, export request, export completion, files and hashes, storage path, import request, mode, target completion status, errors, retry decisions, and reconciliation result. A rerun must be able to distinguish already accepted data from missing or failed data.

Prove Counts, Versions, References, and Search Results

Resource counts are a first control, not the acceptance gate. Reconcile by resource type and partition where practical, then add version counts for history-bearing resources. Compute sample or full hashes only after normalizing fields whose values are expected to change. Run history queries for resources with known edits and deletions. Scan references for missing targets, then exercise the same reads through the authorization context used by applications.

Search parity needs a versioned corpus. Save representative and high-risk queries before migration: patient identifier lookup, date ranges, chained searches, include/revinclude, custom parameters, sorting, pagination, and clinically important cohort queries. Record result IDs and expected ordering only where ordering is part of the client contract.

Worked example: consider a hospital integration estate with a clinician SMART app, a lab-feed pipeline, a quality-report extract, and a FHIR store whose approved scope includes historical versions. Discovery finds that the lab pipeline writes continuously while the quality job can pause. The team chooses incremental copy. During rehearsal, counts match, but a history test shows only the latest Observation versions in the target. The cause is an import path that did not preserve versionId and lastUpdated metadata. Cutover is stopped, the affected staging set is rebuilt, incremental import is rerun with the required metadata, and history queries are reconciled again. Final evidence includes the corrected manifest, source and target history results, reference checks, search corpus results, and an approved exception list. The failure is caught before clinicians are switched because version history is an acceptance criterion, not a post-migration nice-to-have.

• Counts by resource type and migration batch reconcile within approved, explained exceptions.

• Historical-version scope is proven with history queries and version counts.

• References resolve for critical workflows and sampled high-risk resources.

• Search corpus results are semantically equivalent for required queries.

• Every exception has an owner, business impact, remediation, and decommission decision.

Update Applications, SDKs, Endpoints, and Configuration

Application migration is a coordinated release, not a search-and-replace of the base URL. Change endpoint, audience, issuer, permissions, redirect URIs, certificates, secret references, DNS aliases, API gateway routes, timeouts, retry policies, health checks, metadata discovery, and deployment variables as applicable. Review SDK behavior where clients depend on service-specific headers, pagination links, bundle handling, or error responses.

Prefer configuration that allows a controlled switch and fast rollback without rebuilding the application. If a DNS alias or gateway abstraction is used, validate caching and propagation behavior. If clients call the service hostname directly, create a deployment plan by consumer and track exactly which version points to which FHIR endpoint.

The operational concepts in managing APIs in production apply here: observability, staged rollout, incident controls, and measurable client behavior. For this migration, add metadata, search, history, and clinical workflow evidence to the usual HTTP success and latency signals.

Replace SMART on FHIR Proxy Before Its Separate Cutoff

The SMART migration is a security and user-context change. Microsoft's legacy proxy page says the proxy retires on September 21, 2026. Microsoft's newer SMART on FHIR guidance describes native SMART support and identity-provider integration. Do not wait for the FHIR data cutover to discover which applications still depend on proxy-specific callbacks or token contents.

Inventory every SMART client by launch type, client ID, redirect URI, issuer, audience, requested scopes, patient/user/encounter context, token exchange behavior, session lifetime, logout behavior, and any proxy-specific customization. Capture both EHR launch and standalone launch where used. A launch that reaches the application's home page is not sufficient; prove that the correct patient and user context is present and that the app cannot silently switch to a broader data scope.

Test Authorization, Launch Context, and Failure Paths

Run SMART tests with a purpose-built matrix. Include a valid patient launch, valid practitioner launch, standalone launch if supported, wrong tenant, wrong audience, expired token, revoked token or credential, missing scope, unconsented client, invalid redirect URI, missing launch context, mismatched patient context, and emergency-access path if the application supports one. Record token claims only in a protected evidence store and redact secrets.

• Positive: intended clinician and patient context produce only the approved data and workflow.

• Negative: wrong tenant, missing permission, or invalid context fails without leaking patient data.

• Expiry/revocation: stale tokens or credentials no longer authorize FHIR calls.

• Context integrity: the patient displayed by the app matches the patient context delivered through the SMART flow.

• Audit: authorization success and denial can be correlated to user, client, time, and target service.

Recreate Search Parameters, Events, Jobs, and Analytics Integrations

Data transfer can finish while operational behavior is still incomplete. Recreate custom SearchParameter resources, then run and monitor reindex operations before declaring those searches production-ready. Microsoft's selectable search parameters guidance notes that selectable search parameters can change which built-in indexes are enabled, and its reindex guidance warns that reindexing can be performance intensive. Schedule it with the same care as import.

The target supports Azure Health Data Services events, which can publish change notifications through Azure Event Grid. That is not a reason to assume an old proxy-based event integration is equivalent. Compare event type, payload, ordering assumptions, retry behavior, dead-letter handling, idempotency, and downstream side effects. Run end-to-end tests through the consumer, not only a platform event test.

For analytics, update pipelines, linked services, schemas, and refresh schedules, then reconcile outputs. Azure analytics and data integration provides broader platform context, but the migration gate remains FHIR-specific: downstream data must still represent the intended resources, versions, references, and time semantics.

Rehearse Cutover, Freeze, Delta Capture, and Rollback

A cutover should be rehearsed as a timed operational procedure with named decision authority. The sequence differs by migration pattern, but both need a clear moment when the source stops being authoritative for new writes. For lift-and-shift, that may be the start of the write freeze. For incremental copy, it is the start of final delta capture and the point after which unresolved dual writes become unacceptable.

Define rollback as a data decision, not just an endpoint switch. If writes have reached the target after the switch, returning clients to the source without reconciling those writes can lose or duplicate clinical data. Your rollback window therefore needs rules for whether writes are blocked, mirrored, queued, or reconciled back to the source. If safe reverse reconciliation is not possible, the rollback strategy may be isolation and repair on the target rather than reactivating the source for writes.

Run the rehearsal with the same people who will execute production: FHIR platform, application owners, identity/security, network, data migration, operations, clinical/business validators, compliance, and the executive risk owner. A runbook that works only for its author is not a runbook.

Observe Clinical and Operational Integrity After Cutover

Post-cutover monitoring must answer two questions at once: is the platform healthy, and are clinical workflows still semantically correct? A 99.9 percent HTTP success rate can coexist with a wrong patient context, missing historical information, incomplete search cohort, or lost downstream event. Combine platform telemetry with workflow validation and reconciliation signals.

Track request success, latency, authorization denials, token failures, search differences, missing references, import exceptions, event-delivery gaps, analytics refresh failures, queue backlogs, and user-reported clinical impact. Compare to an approved pre-cutover baseline where meaningful, but do not turn historical behavior into a requirement if the target intentionally improves it. The decision record should distinguish expected change from defect.

Define Patient-Safety and Data-Integrity Stop Conditions

Stop conditions should be written before the change window, with authority to act. The incident commander should not have to debate whether a wrong patient banner is serious enough to stop traffic. Immediate stop, isolation, or rollback review is warranted for missing or incorrect patient context, altered clinical results, unauthorized data exposure, unresolved critical resource differences, unexplained reference failures, or a rollback path that is no longer data-safe.

• Missing or incorrect patient, encounter, practitioner, or user context in a clinician-facing workflow.

• Clinically material search results differ without an approved semantic reason.

• Unauthorized read or write succeeds, or an approved critical identity cannot be restored promptly.

• Historical/version behavior required by the workflow is absent or inconsistent.

• References resolve to the wrong resource, fail at scale, or create ambiguous patient linkage.

• Rollback would overwrite or discard accepted post-cutover writes and no safe reconciliation path exists.

For every stop, preserve timestamps, request IDs, resource identifiers, affected client version, token metadata necessary for investigation, configuration versions, and the exact recovery action. Patient-safety review, security incident handling, and technical root-cause analysis may have different evidence-retention requirements; coordinate them rather than letting one cleanup destroy another team's evidence.

Decommission Azure API for FHIR and Preserve Audit Evidence

Decommissioning is the final migration control. Do not delete the source as soon as application traffic drops to zero. First prove that no scheduled job, integration engine, vendor client, SMART callback, analytics pipeline, or break-glass process still depends on it. Confirm that the target has passed the agreed observation period and that the rollback decision has formally expired or changed to target-side recovery.

Then shut down in layers: stop source pipelines and jobs, remove routing and DNS references, revoke legacy app permissions and credentials, remove private endpoints and firewall rules no longer needed, clean migration staging data according to retention policy, archive reconciliation evidence, and decommission the Azure API for FHIR resource according to approved change and records-management procedures. Keep only the evidence required for audit, legal, security, and operational learning.

Post-deadline remediation needs a separate path because Microsoft states that after September 30, 2026 the retired service cannot be accessed through the portal or APIs and is no longer supported. If a dependency is discovered late, treat it as an incident: identify what data and behavior the dependency expected, locate retained migration evidence or downstream copies, rebuild against the Health Data Services FHIR service, run the same authorization and semantic tests, and obtain explicit business acceptance for any data that cannot be reconstructed. Do not quietly point the missed client at the target and assume equivalence.

A durable evidence packet should include the estate inventory, source and target configuration snapshots, support cases, manifests and hashes, import/export job records, exception ledger, version and reference reconciliation, search corpus results, identity and SMART test results, application release versions, cutover timeline, stop/rollback decisions, monitoring evidence, and final decommission approvals. That packet is what lets a later auditor or incident responder explain not only that the migration happened, but why it was safe to retire the source.

A zero-surprise Azure API for FHIR migration ends when the team can prove clinical and operational equivalence for the scope it approved. Resource and version counts reconcile; historical behavior is preserved where required; references resolve; critical searches return the expected clinical meaning; applications use the intended Health Data Services endpoint and authority; SMART workflows pass both positive and negative authorization tests; events, jobs, and analytics are functioning; patient-safety stop conditions have named owners; and rollback or target-side recovery remains safe until the acceptance window closes.

The permanent lesson is that a FHIR service retirement is an API contract, identity, data-history, and clinical workflow migration at the same time. If a missed dependency appears after retirement, use the retained ledger and evidence to rebuild it deliberately rather than guessing at source behavior. Teams strengthening the underlying REST, authentication, authorization, integration, testing, logging, versioning, performance, and API-security foundations can review the Refonte Learning APIs Developer Program. The program is a three-month API-development program at roughly 10 to 12 hours per week with basic programming knowledge recommended; it is not presented as FHIR, SMART on FHIR, Azure Health Data Services, or healthcare-compliance training.