JSON Admin API MDM Deprecation Migration

The MDM endpoints in the JSON Admin API (under /mdm/{module_id}/...) have been deprecated in favour of the corresponding $mdm-* operations on the cdr-endpoint-fhir module. This page lists each deprecated endpoint and the FHIR operation to call instead.

Why This Change

FHIR data access should pass through a FHIR endpoint so that the platform's full authorization model — including the CdrAuthorizationInterceptor and the user/role/permission stack on cdr-endpoint-fhir — is enforced consistently. The admin-json MDM endpoints predate this model and bypass parts of it. The FHIR $mdm-* operations provide the same functional capabilities behind the proper authorization gate.

Removal Timeline

The deprecated admin-json MDM endpoints continue to work today and are flagged deprecated: true in the generated OpenAPI spec. They are scheduled for removal in 2028.08.R01 or later. Plan migrations accordingly.

The mdm-algorithms and mdm-metrics endpoints on MdmController are not deprecated and remain on the JSON Admin API.

Endpoint Mapping

The table below maps each deprecated admin-json endpoint to its $mdm-* equivalent on cdr-endpoint-fhir. The FHIR operations are documented in the HAPI FHIR MDM Operations guide.

Migrating a Call

The two APIs are functionally equivalent but the request shape differs. The admin-json variants take a JSON request body keyed by camelCase field names; the FHIR variants take a Parameters resource (FHIR JSON or XML) and run on the FHIR endpoint base URL of the cdr-endpoint-fhir module — typically /fhir rather than /mdm/{module_id}.

For example, to query links you would change:

GET http://localhost:9000/mdm/mdm/query-links?goldenResourceId=Patient/1

to the equivalent FHIR call (note the different port and the operation name):

GET http://localhost:8000/fhir/$mdm-query-links?goldenResourceId=Patient/1

See the FHIR MDM Operations documentation for the request shape of each operation.