Operations and management
Use this page for the server surfaces that support health checks, cache lifecycle, saved-mapping administration, and other operational workflows around execution.
Shared operational surfaces
| Operational goal | Endpoint | Availability | What it is for |
|---|---|---|---|
| Read server metadata | GET / | Community + Enterprise | Version, upstream FHIR target, uptime, and loaded context packages. |
| Probe service health | GET /health | Community + Enterprise | Liveness and readiness checks. |
| Reload mapping and ConceptMap caches | POST /$recache | Community + Enterprise, when mapping sources exist | Refresh mappings and aliases from the configured sources. |
| Use the deprecated recache path during transition | POST /recache | Community + Enterprise, when mapping sources exist | Same refresh behavior, but deprecated and warning-bearing. |
| Retrieve saved mapping source text | GET /Mapping/{mappingId} | Community + Enterprise, when mapping sources exist | Returns the saved FUME expression for inspection or export. |
Every /Mapping/* administrative route depends on the same mapping-source prerequisite as saved-mapping execution. Configure at least one source through FHIR_SERVER_BASE or MAPPINGS_FOLDER before you expect mapping retrieval or cache refresh to succeed.
Use GET / for operator-facing server context
GET / is the read-only metadata endpoint for the current server instance.
Use it when an operator or integration owner needs to confirm which FUME version is running, which upstream FHIR server is configured, how long the service has been up, or which context packages are loaded.
This is useful for diagnostics and environment confirmation, but it is not the best routine probe for load balancers or orchestrators. For that, use GET /health.
Use GET /health for automated health probing
GET /health is the stability-focused probe endpoint.
Use it for liveness and readiness checks when the caller only needs to know whether the service is up enough to accept traffic.
Community and Enterprise share the route and the core purpose. Enterprise may expose additional warm-up detail in its response contract, but the route should still be treated as the automation-friendly health surface.
Use POST /$recache after mapping or ConceptMap changes
POST /$recache is the preferred cache refresh entry point.
Call it after you add, replace, or remove saved mappings in the configured sources, or after you need $translate() calls to pick up fresh ConceptMap content.
On success, the server reloads mappings and aliases into cache and returns the mapping keys that were loaded.
If the deployment has no configured mapping sources, recache is unavailable and returns 405 because there is nothing to refresh.
Deprecated compatibility route: POST /recache
POST /recache performs the same refresh work, but it is deprecated.
Keep it only for compatibility with older callers. New integrations should move to POST /$recache so they do not depend on a route that is expected to disappear.
Disabled read form: GET /recache
GET /recache is intentionally unsupported because recache changes server state.
If a client tries it, the server returns 405 with guidance to use POST /$recache instead.
Retrieve and manage saved mappings
The saved-mapping lifecycle surfaces split cleanly between shared read access and Enterprise write access.
| Task | Endpoint | Availability | Notes |
|---|---|---|---|
| Read the saved mapping source | GET /Mapping/{mappingId} | Community + Enterprise | Returns the stored FUME expression as application/vnd.outburn.fume. |
| Execute the saved mapping | POST /Mapping/{mappingId} | Community + Enterprise | Use Execution patterns for the runtime semantics. |
| Create or replace the saved mapping source | PUT /Mapping/{mappingId} | Enterprise only | The base PUT route is reserved for mapping update, not transform execution. |
| Delete the saved mapping | DELETE /Mapping/{mappingId} | Enterprise only | Removes the mapping from the primary writable store when deletes are enabled. |
Community keeps the base write route unimplemented so the shared Community server surface stays side-effect free. Enterprise turns that reserved route into managed mapping create, update, and delete behavior.
When Enterprise write operations are disabled or no writable store is available, the deployment needs its write policy corrected before PUT or DELETE can succeed. The key setting for that policy is MAPPINGS_PRIMARY_WRITABLE_STORE, which works together with MAPPINGS_FOLDER and FHIR_SERVER_BASE.
Enterprise adds write-side mapping management on the base /Mapping/{mappingId} route. That is why transform execution via PUT requires at least one extra path segment, as described on Execution patterns.
Use template endpoints as authoring accelerators
Enterprise also exposes a template surface under GET /Template/{templateId}.
Use it when you want the server to generate a starting FUME template for a known profile, resource, datatype, or extension instead of retrieving or executing an existing mapping.
Two usage patterns matter most:
GET /Template/$list?type=...lists available template IDs for a supported template category.GET /Template/{templateId}returns the generated template source itself.
This surface is useful during authoring and onboarding, not during normal request execution. Once the mapping is ready to run, move back to the saved-mapping execution routes.
Pair this page with the product-specific OpenAPI pages when you need the exact operation list or payload details.