FHIR Operation Framework | Medplum

On this page

In addition to the standard API endpoints for creating, reading, and updating resources, FHIR offers a variety of RPC-like Operation APIs to expose arbitrary functionality as a FHIR API. Each API endpoint is defined by an OperationDefinition resource, which provides information about how to call the API and what to expect in response.

Operation Definition [​](/content/docs/api/fhir/operations#operation-definition "Direct link to Operation Definition"/index.html)

For example, consider the ValueSet/$validate-code operation, which is summarized below:

OperationDefinition JSON

{
  "resourceType": "OperationDefinition",
  "url": "http://hl7.org/fhir/OperationDefinition/ValueSet-validate-code",
  "status": "active",
  "kind": "operation",
  // Endpoint configuration
  "code": "validate-code",
  "resource": ["ValueSet"],
  "system": false,
  "type": true,
  "instance": true,
  "parameter": [
    // Input Parameters
    {
      "use": "in",
      "name": "url",
      "documentation": "Value set canonical URL",
      "min": 0,
      "max": "1",
      "type": "uri"
    },
    {
      "use": "in",
      "name": "valueSet",
      "documentation": "The value set is provided directly as part of the request",
      "min": 0,
      "max": "1",
      "type": "ValueSet"
    },
    {
      "use": "in",
      "name": "code",
      "documentation": "The code that is to be validated",
      "min": 0,
      "max": "1",
      "type": "code"
    },
    {
      "use": "in",
      "name": "system",
      "documentation": "The system for the code that is to be validated",
      "min": 0,
      "max": "1",
      "type": "uri"
    },
    {
      "use": "in",
      "name": "display",
      "documentation": "The display associated with the code, if provided",
      "min": 0,
      "max": "1",
      "type": "string"
    },
    {
      "use": "in",
      "name": "coding",
      "documentation": "A coding to validate",
      "min": 0,
      "max": "1",
      "type": "Coding"
    },
    {
      "use": "in",
      "name": "codeableConcept",
      "documentation": "A full codeableConcept to validate",
      "min": 0,
      "max": "1",
      "type": "CodeableConcept"
    },
    // Output Parameters
    {
      "use": "out",
      "name": "result",
      "documentation": "True if the concept details supplied are valid",
      "min": 1,
      "max": "1",
      "type": "boolean"
    },
    {
      "use": "out",
      "name": "message",
      "documentation": "Error details, if result = false; otherwise may contain hints and warnings",
      "min": 0,
      "max": "1",
      "type": "string"
    },
    {
      "use": "out",
      "name": "display",
      "documentation": "A valid display for the concept if the system wishes to display this to a user",
      "min": 0,
      "max": "1",
      "type": "string"
    }
  ]
}

This definition supplies the information needed to correctly call the operation API endpoint:

Invoking an Operation [​](/content/docs/api/fhir/operations#invoking-an-operation "Direct link to Invoking an Operation"/index.html)

Given the information from the OperationDefinition, we can construct a request to the operation API endpoint. For each in parameter, corresponding entries may appear in the request Parameters.parameter array. Value types must match the OperationDefinition.

Request:

const result = await medplum.post(medplum.fhirUrl('ValueSet', '$validate-code').toString(), {
  resourceType: 'Parameters',
  parameter: [
    { name: 'url', valueUri: 'http://hl7.org/fhir/ValueSet/condition-severity' },
    { name: 'coding', valueCoding: { system: 'http://snomed.info/sct', code: '255604002' } },
  ],
});

curl 'https://api.medplum.com/fhir/R4/ValueSet/$validate-code' \  
  -X POST \  
  -H "Content-Type: application/fhir+json" \  
  -H "Authorization: Bearer $MY_ACCESS_TOKEN" \  
  -d '{"resourceType":"Parameters","parameter":[{"name":"url","valueUri":"http://hl7.org/fhir/ValueSet/condition-severity"},{"name":"coding","valueCoding":{"system":"http://snomed.info/sct","code":"255604002"}}]}'

Response: (200 OK)

{
  "resourceType": "Parameters",
  "parameter": [
    { "name": "result", "valueBoolean": true },
    { "name": "display", "valueString": "Mild (qualifier value)" }
  ]
}

Via GET Request [​](/content/docs/api/fhir/operations#via-get-request "Direct link to Via GET Request"/index.html)

In some cases, it may be simpler to invoke an operation with a GET request and encode the input parameters in the query string of the request URL. For example, the following operation requests are equivalent:

curl 'https://api.medplum.com/fhir/R4/ValueSet/$validate-code' \  
  -X POST \  
  -H "Content-Type: application/fhir+json" \  
  -H "Authorization: Bearer $MY_ACCESS_TOKEN" \  
  -d '{"resourceType":"Parameters","parameter":[{"name":"url","valueUri":"http://hl7.org/fhir/ValueSet/condition-severity"},{"name":"coding","valueCoding":{"system":"http://snomed.info/sct","code":"255604002"}}]}'

curl 'https://api.medplum.com/fhir/R4/ValueSet/$validate-code' \  
  --get \  
  -H "Authorization: Bearer $MY_ACCESS_TOKEN" \  
  -d 'url=http://hl7.org/fhir/ValueSet/condition-severity' \  
  -d 'system=http://snomed.info/sct' \  
  -d 'code=255604002'

This is possible when the request is idempotent and contains only simple input parameter types, i.e.

Reading the Response [​](/content/docs/api/fhir/operations#reading-the-response "Direct link to Reading the Response"/index.html)

For each out parameter in the response, the typed value(s) are recorded in the Parameters.parameter array. Multiple values for a given output parameter will appear as multiple entries in the array, not a nested array in the value[x] field.

Error Responses [​](/content/docs/api/fhir/operations#error-responses "Direct link to Error Responses"/index.html)

In case of an error, the server will return an HTTP status code in the 4xx-5xx range. The response body will contain an OperationOutcome resource with details about the error.

For example, if the specified ValueSet could not be found by URL:

{
    "resourceType": "OperationOutcome",
    "issue": [
        {
            "severity": "error",
            "code": "invalid",
            "details": {
                "text": "ValueSet http://example.com/ValueSet/missing not found"
            }
        }
    ]
}

Operation Documentation [​](/content/docs/api/fhir/operations#operation-documentation "Direct link to Operation Documentation"/index.html)

Details about the FHIR Operations supported by Medplum server are organized below by category. For information about other available operations, see the complete list from the FHIR specification.

Terminology Operations [​](/content/docs/api/fhir/operations#terminology-operations "Direct link to Terminology Operations"/index.html)

Operations for managing CodeSystem, ConceptMap, and ValueSet resources.

CodeSystem:

ConceptMap:

ValueSet:

Patient Operations [​](/content/docs/api/fhir/operations#patient-operations "Direct link to Patient Operations"/index.html)

Operations specific to Patient resources.

Bot Operations [​](/content/docs/api/fhir/operations#bot-operations "Direct link to Bot Operations"/index.html)

Deploy, execute, and extend Medplum Bots.

Resource Validation & Transformation [​](/content/docs/api/fhir/operations#resource-validation--transformation "Direct link to Resource Validation & Transformation"/index.html)

Validate resources and transform data structures.

Data Export & Import [​](/content/docs/api/fhir/operations#data-export--import "Direct link to Data Export & Import"/index.html)

Bulk data operations and format conversions.

Clinical Decision Support [​](/content/docs/api/fhir/operations#clinical-decision-support "Direct link to Clinical Decision Support"/index.html)

Operations for measures, clinical plans, charges, and AI assistance.

Project & System Administration [​](/content/docs/api/fhir/operations#project--system-administration "Direct link to Project & System Administration"/index.html)

Project management and system operations.

Authentication & Security [​](/content/docs/api/fhir/operations#authentication--security "Direct link to Authentication & Security"/index.html)

Client application, credential, and user management operations.