{ "openapi": "3.0.3", "info": { "title": "FUME Community API", "version": "3.0.6", "description": "FHIR-Utilizing Mapping Engine - Community Edition. \nEvaluate ad-hoc FUME expressions or execute saved StructureMap mappings.\n" }, "tags": [ { "name": "Server", "description": "General server metadata endpoints." }, { "name": "Evaluation", "description": "Ad-hoc evaluation endpoints." }, { "name": "Health", "description": "Liveness/readiness endpoints." }, { "name": "Cache", "description": "Cache and mapping refresh endpoints." }, { "name": "Mapping", "description": "Saved mapping retrieval and execution endpoints." } ], "servers": [ { "url": "/", "description": "Current server" } ], "components": { "schemas": { "ServerInfo": { "type": "object", "properties": { "fume_version": { "type": "string", "example": "FUME Community v3.0.0" }, "fhir_server": { "type": "string", "example": "http://hapi-fhir:8080/fhir" }, "uptime": { "type": "string", "example": "2 days, 15 hours, 57 minutes and 26 seconds" }, "context_packages": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "hl7.fhir.r4.core" }, "version": { "type": "string", "example": "4.0.1" } } } } } }, "HealthResponse": { "type": "object", "properties": { "status": { "type": "string", "example": "UP" } } }, "DiagnosticsObject": { "type": "object", "properties": { "error": { "type": "array", "items": { "$ref": "#/components/schemas/Diagnostic" } }, "warning": { "type": "array", "items": { "$ref": "#/components/schemas/Diagnostic" } }, "debug": { "type": "array", "items": { "$ref": "#/components/schemas/Diagnostic" } } }, "required": [ "error", "warning", "debug" ] }, "Diagnostic": { "type": "object", "description": "A single diagnostic entry emitted during evaluation/validation.", "additionalProperties": false, "properties": { "code": { "type": "string", "example": "F5120" }, "position": { "type": "integer", "example": 57 }, "start": { "type": "integer", "example": 52 }, "line": { "type": "integer", "example": 2 }, "instanceOf": { "type": "string", "example": "Patient" }, "fhirElement": { "type": "string", "example": "extension[data-absent-reason].value" }, "bindingStrength": { "type": "string", "example": "required" }, "expansionMode": { "type": "string", "example": "full" }, "value": { "description": "The value that triggered the diagnostic (may be any JSON type)." }, "message": { "type": "string", "example": "Value \"abc\" for \"extension[data-absent-reason].value\" in \"Patient\" is not in the required ValueSet." }, "severity": { "type": "integer", "example": 12 }, "level": { "type": "string", "example": "invalid" }, "timestamp": { "type": "integer", "format": "int64", "example": 1771327039703 } } }, "VerboseReport": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "status": { "type": "integer", "description": "HTTP-like status code of the evaluation result (e.g. 200, 206)", "example": 206 }, "result": { "description": "The raw evaluation result" }, "diagnostics": { "$ref": "#/components/schemas/DiagnosticsObject" }, "executionId": { "type": "string" } } }, "FumeError": { "type": "object", "description": "Structured FUME error payload returned on compilation/evaluation failures.", "properties": { "__isFumeError": { "type": "boolean" }, "__isFlashError": { "type": "boolean" }, "message": { "type": "string" }, "code": { "type": "string" }, "name": { "type": "string" }, "value": { "type": "string" }, "token": { "type": "string" }, "cause": { "type": "string" }, "line": { "oneOf": [ { "type": "string" }, { "type": "integer" } ] }, "start": { "oneOf": [ { "type": "string" }, { "type": "integer" } ] }, "position": { "oneOf": [ { "type": "string" }, { "type": "integer" } ] } }, "example": { "__isFumeError": true, "__isFlashError": false, "message": "Missing expression after \":\". Objects must contain only key-value pairs", "code": "F1101", "name": "", "value": "", "token": ":", "cause": "", "line": 1, "start": 6, "position": 7 } }, "RecacheResponse": { "type": "object", "description": "Recache result describing what was loaded into cache.", "properties": { "message": { "type": "string", "example": "The following Mappings were loaded to cache" }, "mappings": { "type": "array", "items": { "type": "string" }, "description": "List of mapping keys loaded into cache" } }, "example": { "message": "The following Mappings were loaded to cache", "mappings": [ "Patient12", "exampleForRepo" ] } }, "RecacheResponseDeprecated": { "type": "object", "description": "Recache result for the deprecated POST /recache endpoint, which includes a deprecation warning.", "properties": { "message": { "type": "string", "example": "The following Mappings were loaded to cache" }, "mappings": { "type": "array", "items": { "type": "string" }, "description": "List of mapping keys loaded into cache" }, "deprecated": { "type": "boolean", "description": "Whether the recache endpoint is deprecated (will emit a warning if true)" } }, "example": { "message": "The following Mappings were loaded to cache", "mappings": [ "Patient12", "exampleForRepo" ], "deprecated": true } } }, "parameters": { "verbose": { "name": "verbose", "in": "query", "required": false, "description": "When set to `true` (case-insensitive) or `1`, returns the full evaluation report instead of the raw result.", "schema": { "type": "string" } } } }, "paths": { "/": { "get": { "tags": [ "Server" ], "summary": "Server info", "description": "Returns basic server information including version, configured FHIR server, uptime, and loaded context packages.", "operationId": "getServerInfo", "responses": { "200": { "description": "Server info", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerInfo" } } } } } }, "post": { "tags": [ "Evaluation" ], "summary": "Evaluate ad-hoc expression", "description": "Evaluate an ad-hoc FUME expression. The request body can be a JSON object with `fume` (required), `input`, and `contentType` fields.", "operationId": "evaluateExpression", "parameters": [ { "$ref": "#/components/parameters/verbose" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "fume" ], "properties": { "fume": { "type": "string", "description": "FUME expression to evaluate", "example": "{ resourceType: id }" }, "input": { "description": "Input data for the expression", "example": { "resourceType": "Patient", "id": "123" } }, "contentType": { "type": "string", "description": "Content type for input conversion", "example": "application/json" } } }, "examples": { "validRequest": { "summary": "Valid request", "value": { "fume": "{ resourceType: id }", "input": { "resourceType": "Patient", "id": "123" }, "contentType": "application/json" } }, "invalidRequest": { "summary": "Invalid request (missing fume)", "value": { "input": { "resourceType": "Patient", "id": "123" }, "contentType": "application/json" } }, "invalidRequest2": { "summary": "Invalid request (invalid fume)", "value": { "fume": "{ resourceType: id ", "input": { "resourceType": "Patient", "id": "123" }, "contentType": "application/json" } }, "invalidRequest3": { "summary": "Invalid request (unsupported content type)", "value": { "fume": "{ resourceType: id }", "input": { "resourceType": "Patient", "id": "123" }, "contentType": "application/invalid" } }, "partialResult": { "summary": "Partial result (with diagnostics)", "value": { "fume": "InstanceOf: Patient\\n* extension[data-absent-reason].value = \"abc\"" } } } } } }, "responses": { "200": { "description": "Evaluation result", "content": { "application/json": { "schema": {}, "examples": { "result": { "summary": "Response", "value": { "Patient": "123" } } } } } }, "206": { "description": "Partial evaluation result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerboseReport" } } } }, "400": { "description": "Missing or empty `fume` expression", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FumeError" } } } }, "415": { "description": "Unsupported media type", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string" } } }, { "$ref": "#/components/schemas/VerboseReport" } ] }, "examples": { "unsupportedMediaType": { "summary": "Unsupported media type", "value": { "message": "Unsupported Content-Type: 'application/invalid'", "code": "UNSUPPORTED_MEDIA_TYPE" } }, "verboseUnsupportedMediaType": { "summary": "Unsupported media type (verbose mode)", "value": { "ok": false, "status": 415, "diagnostics": { "error": [ { "code": "UNSUPPORTED_MEDIA_TYPE", "message": "Unsupported content-type", "severity": 1, "level": "error", "timestamp": 1771328556787 } ], "warning": [], "debug": [] }, "executionId": "4362008e-3736-4510-94a2-f9969a0565c9" } } } } } }, "422": { "description": "Expression compilation or evaluation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FumeError" } } } } } } }, "/health": { "get": { "tags": [ "Health" ], "summary": "Health probe", "description": "Health check endpoint for load balancers and liveness/readiness probes.", "operationId": "healthCheck", "responses": { "200": { "description": "Server is healthy", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthResponse" } } } } } } }, "/$recache": { "post": { "tags": [ "Cache" ], "summary": "Reload mappings", "description": "Reloads mappings and aliases from the configured sources into cache. Flushes the ConceptMap cache. Available only when at least one mapping source is configured.", "operationId": "recache", "responses": { "200": { "description": "Mappings reloaded successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecacheResponse" } } } }, "405": { "description": "Method not allowed. No mapping sources configured." }, "500": { "description": "Cache could not be refreshed" } } } }, "/recache": { "get": { "tags": [ "Cache" ], "summary": "Recache (method not allowed)", "description": "Recache has side-effects, so GET is no longer supported. Use `POST /$recache` instead.", "operationId": "recacheGetDisabled", "deprecated": true, "responses": { "405": { "description": "Method not allowed. Use POST /$recache." } } }, "post": { "tags": [ "Cache" ], "summary": "Reload mappings (deprecated)", "description": "Same as `POST /$recache`, but deprecated. Emits a warning in logs and a Warning response header. Will be removed in future releases.", "operationId": "recacheDeprecated", "deprecated": true, "responses": { "200": { "description": "Mappings reloaded successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecacheResponseDeprecated" } } } }, "405": { "description": "Method not allowed. No mapping sources configured." }, "500": { "description": "Cache could not be refreshed" } } } }, "/Mapping/{mappingId}": { "get": { "tags": [ "Mapping" ], "summary": "Fetch mapping expression", "description": "Fetches the FUME expression for a saved mapping.", "operationId": "getMappingExpression", "parameters": [ { "name": "mappingId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The ID of the saved mapping" } ], "responses": { "200": { "description": "Mapping expression (FUME source)", "content": { "application/vnd.outburn.fume": { "schema": { "type": "string" }, "examples": { "exampleMapping": { "summary": "Example mapping expression", "value": "// Example FUME mapping expression\nInstanceOf: Patient\n* name.text = first_name & ' ' & last_name\n" } } } } }, "404": { "description": "Mapping not found" } } }, "post": { "tags": [ "Mapping" ], "summary": "Execute saved mapping", "description": "Invokes the saved mapping transform. The request body is treated as the input, converted according to the request Content-Type.", "operationId": "executeMappingById", "parameters": [ { "name": "mappingId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The ID of the saved mapping" }, { "$ref": "#/components/parameters/verbose" } ], "requestBody": { "description": "Input data for the mapping", "content": { "application/json": { "schema": { "type": "object" } }, "application/fhir+json": { "schema": { "type": "object" } }, "application/xml": { "schema": { "type": "string" } }, "application/fhir+xml": { "schema": { "type": "string" } }, "text/csv": { "schema": { "type": "string" } }, "x-application/hl7-v2+er7": { "schema": { "type": "string" } } } }, "responses": { "200": { "description": "Mapping result (any JSON). When `?verbose` is enabled, returns a VerboseReport." }, "206": { "description": "Partial result" }, "404": { "description": "Mapping not found" }, "415": { "description": "Unsupported media type" }, "422": { "description": "Compilation, transform, or evaluation failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FumeError" } } } } } } }, "/Mapping/{mappingId}/{subroute}": { "post": { "tags": [ "Mapping" ], "summary": "Execute saved mapping with subroutes", "description": "Same as `POST /Mapping/{mappingId}`, but path segments after the mapping ID are captured as routing metadata and exposed via `$fumeHttpInvocation`.\nOpenAPI cannot model Express-style multi-segment wildcard routes. The actual server route supports an arbitrary number of path segments after `{mappingId}` (e.g. `POST /Mapping/{mappingId}/a/b/123`).\nThis path is documented with a single `{subroute}` segment for documentation purposes only. Swagger UI \"Try it out\" (and many generated clients) cannot reliably invoke the multi-segment form.", "operationId": "executeMappingWithSubroutes", "parameters": [ { "name": "mappingId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The ID of the saved mapping" }, { "name": "subroute", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Documentation-only placeholder for the wildcard route remainder. For real multi-segment usage, call the endpoint as `/Mapping/{mappingId}/...` with one or more additional path segments (e.g. `/Mapping/{mappingId}/a/b/123`)." }, { "$ref": "#/components/parameters/verbose" } ], "requestBody": { "description": "Input data for the mapping", "content": { "application/json": { "schema": { "type": "object" } }, "application/fhir+json": { "schema": { "type": "object" } }, "application/xml": { "schema": { "type": "string" } }, "application/fhir+xml": { "schema": { "type": "string" } }, "text/csv": { "schema": { "type": "string" } }, "x-application/hl7-v2+er7": { "schema": { "type": "string" } } } }, "responses": { "200": { "description": "Mapping result (any JSON). When `?verbose` is enabled, returns a VerboseReport." }, "206": { "description": "Partial result" }, "404": { "description": "Mapping not found" }, "415": { "description": "Unsupported media type" }, "422": { "description": "Compilation, transform, or evaluation failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FumeError" } } } } } }, "put": { "tags": [ "Mapping" ], "summary": "Execute saved mapping with subroutes (PUT)", "description": "Same as the POST subroute form, but with method PUT. Transform is invoked only when there is at least one path segment after the mapping ID. `PUT /Mapping/{mappingId}` without subroutes is reserved for mapping updates.", "operationId": "executeMappingWithSubroutesPut", "parameters": [ { "name": "mappingId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The ID of the saved mapping" }, { "name": "subroute", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Documentation-only placeholder for the wildcard route remainder (required for PUT transforms). Use one or more additional path segments after `{mappingId}` when invoking manually." }, { "$ref": "#/components/parameters/verbose" } ], "requestBody": { "description": "Input data for the mapping", "content": { "application/json": { "schema": { "type": "object" } }, "application/fhir+json": { "schema": { "type": "object" } }, "application/xml": { "schema": { "type": "string" } }, "application/fhir+xml": { "schema": { "type": "string" } }, "text/csv": { "schema": { "type": "string" } }, "x-application/hl7-v2+er7": { "schema": { "type": "string" } } } }, "responses": { "200": { "description": "Mapping result (any JSON). When `?verbose` is enabled, returns a VerboseReport." }, "206": { "description": "Partial result" }, "404": { "description": "Mapping not found" }, "415": { "description": "Unsupported media type" }, "422": { "description": "Compilation, transform, or evaluation failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FumeError" } } } } } } } } }