Migrate from HAPI to Aidbox

HAPI FHIR and Aidbox both implement the FHIR spec, but they differ in how they store data, validate resources, and handle search, subscriptions, and access control. This guide walks through the pieces of a HAPI deployment you need to account for, and the steps to move data and configuration into Aidbox.

There is no one-click migration tool. Plan the migration in stages: map your configuration first, run a trial migration against a copy of your data, verify the result, then cut over.

Key differences

• Storage: Aidbox stores each resource type as jsonb rows in PostgreSQL rather than a normalized relational schema, and does not index every search parameter by default. See Create indexes.
• Validation: Aidbox validates against loaded StructureDefinitions instead of HAPI's interceptor-based validators. See Migrate custom resources.
• Subscriptions: Aidbox's native topic-based subscriptions replace polling and webhook subscriptions built around the FHIR Subscription resource. See Migrate subscriptions.
• Access control: Authorization is declarative access policies rather than Java interceptor code. See Migrate access control rules.
• Terminology: Aidbox's terminology module can serve codes from an external server, from resources loaded locally, or both at once. See Migrate terminology.

Before you start

• Match your FHIR version. Note which FHIR version your HAPI server runs (R4, R4B, or R5) and provision your Aidbox instance with the same version.
• Inventory custom content. List every custom StructureDefinition, SearchParameter, and Subscription your HAPI deployment defines. Each has a direct but not identical equivalent in Aidbox, covered below.
• Check your interceptors. HAPI deployments often carry custom Java interceptors for validation, authorization, or request rewriting. Aidbox replaces most of these with declarative configuration (access policies, StructureDefinition-based validation) rather than code, so plan to reimplement interceptor logic as configuration.
• Have a rollback plan. Keep your HAPI instance and its database running read-only until you've verified the Aidbox instance in production.

Set up your target Aidbox instance

Deploy Aidbox before moving any data, so you can load into a running, licensed instance.

Migrate custom resources

HAPI defines custom resources through StructureDefinition. Aidbox uses the same resource for this.

Migrate custom search parameters

Recreate any custom SearchParameter resources from HAPI in Aidbox before loading data, since Aidbox indexes on load and a search parameter added after the fact does not retroactively index existing resources without a reindex.

Migrate subscriptions

Rebuild your HAPI subscriptions as Aidbox topic-based subscriptions rather than porting them as standard FHIR Subscription resources. They scale better under high write volume and support destinations like Kafka, SNS, and webhooks directly.

Migrate access control rules

HAPI authorization interceptors don't carry over as code. Reimplement your authorization rules as Aidbox access policies, and reuse your existing SMART on FHIR client configuration if you have one.

Migrate terminology

If your HAPI deployment points to an external terminology server, such as Health Samurai's terminology SaaS, Aidbox's terminology module can keep using it. You can also load CodeSystems, ValueSets, and ConceptMaps into Aidbox's FHIR Artifact Registry and serve them locally, or combine both: run in hybrid mode, where Aidbox serves what it has loaded locally and falls back to the external server for everything else.

Migrate the data

Export your resources from HAPI using the standard FHIR Bulk Data Export operation, $export, which HAPI implements the same way Aidbox does. Aidbox exposes the matching endpoint for reference:

Load the resulting NDJSON into Aidbox with /fhir/$import. It skips validation and runs fastest, so use it once you've already validated your data against your target profiles in a trial run.

For a smaller dataset, a transactional bundle can be the better option: it validates every resource as part of the transaction and rolls back the whole bundle if one entry fails, so you don't have to separately validate the load afterward.

Validate the migrated data

Aidbox validates resources against loaded StructureDefinitions, which can be stricter about some constraints than HAPI's default validator. Run a validation pass over your imported data and fix any resources that fail before cutting over.

If you loaded data with /fhir/$import, which skips validation, run $batch-validate afterward to check the resources already in the database asynchronously and get an offender-indexed report of what fails and why.

Create indexes

Aidbox stores resources as jsonb and does not create a database index for every search parameter by default. A search parameter works without one, but Postgres falls back to a sequential scan, which gets slow as a table grows. Plan to create indexes for the search parameters your clients actually query before you cut over.

Aidbox can suggest an index for a given resource type and search parameter, and, once traffic hits the new instance, surface which search parameter shapes are actually hot and lack a backing index. Run your usual client queries against the migrated instance during your trial run, then check the suggestions before cutover.

Set up backups before cutover

Before you point production traffic at the new instance, put a backup schedule in place.

Other Aidbox features

Once your migration is running, these are worth a look. None of them are required for cutover.

Checklist

• Aidbox instance deployed, licensed, and set to the source FHIR version
• Custom resources recreated using StructureDefinition
• Custom search parameters recreated
• Subscriptions rebuilt as Aidbox topic-based subscriptions
• Access policies written to replace HAPI interceptors
• Terminology resources migrated or external terminology server repointed
• Data exported from HAPI and imported into Aidbox in a trial run
• Imported data validated against your target StructureDefinitions
• Indexes created for the search parameters your clients query
• Client applications repointed and integrations retested
• Backup schedule configured on the new instance
• Production data migrated and HAPI instance kept read-only as a fallback