ballerinax/health.fhir.templates.international401.specimen Ballerina library

FHIR Specimen API Template

This Ballerina-based template implementation provides a RESTful FHIR API for managing Specimen resources, adhering to the FHIR R4 specification. The API is designed to support CRUD operations International FHIR R4 Specimen FHIR API.

Note: If you are having FHIR profiles from regional or custom implementation guides, you can use the Ballerina Health tool to generate the FHIR API templates for the FHIR profiles. For more information, see the Ballerina Health tool.

• Ballerina (2201.10.2 or later)
• VSCode as the IDE and install the required vscode plugins
  • Ballerina (https://marketplace.visualstudio.com/items?itemName=WSO2.ballerina)
  • Ballerina Integrator (https://marketplace.visualstudio.com/items?itemName=WSO2.ballerina-integrator)

bal new -t healthcare/health.fhir.r4.international401.specimen SpecimenAPI

Run the Ballerina project created by the service template by executing:

bal run

Once successfully executed, the listener will be started at port 9090. Then, you can invoke the service using the following curl command:

curl http://localhost:9090/fhir/r4/Specimen

Now, the service will be invoked and return an OperationOutcome, until the code template is implemented completely.

Note: This template is designed to be used as a starting point for implementing the FHIR API. The template is not complete and will return an OperationOutcome until the code is implemented.

GET /fhir/r4/Specimen/{id}

• Response: Returns a Specimen resource or an OperationOutcome if not found.

GET /fhir/r4/Specimen/{id}/_history/{vid}

• Response: Returns a specific historical version of a Specimen resource.

GET /fhir/r4/Specimen

• Response: Returns a Bundle containing matching Specimen resources.

POST /fhir/r4/Specimen

• Request Body: Specimen resource.
• Response: Returns the created Specimen resource.

PUT /fhir/r4/Specimen/{id}

• Request Body: Updated Specimen resource.
• Response: Returns the updated Specimen resource.

PATCH /fhir/r4/Specimen/{id}

• Request Body: JSON Patch object.
• Response: Returns the updated Specimen resource.

DELETE /fhir/r4/Specimen/{id}

• Response: Returns an OperationOutcome indicating success or failure.

GET /fhir/r4/Specimen/{id}/_history

• Response: Returns a Bundle of historical versions of the Specimen resource.

GET /fhir/r4/Specimen/_history

• Response: Returns a Bundle of historical versions of all Specimen resources.

The template is designed to work as a Facade API to expose your data as in FHIR. The following are the key steps which you can follow to implement the business logic:

• Handle business logic to work with search parameters.
• Implement the source system backend connection logic to fetch data.
• Perform data mapping inside the service to align with the FHIR models.

Modify apiConfig in the fhirr4:Listener initialization if needed to adjust service settings.

The apiConfig object is used to configure the FHIR API. By default, it consists of the search parameters for the FHIR API defined for the Implementation Guide. If there are custom search parameters, they can be defined in the apiConfig object. Following is an example of how to add a custom search parameter:

searchParameters: [
  ....
  {
      name: "custom-search-parameter", // Custom search parameter name
      active: true // Whether the search parameter is active
      information: { // Optional information about the search parameter
          description: "Custom search parameter description",
          builtin: false,
      }
  }
]

Following are the steps to add a custom operation to the FHIR API template:

1. The apiConfig object is used to configure the FHIR API. By default, it consists of the operations for the FHIR API defined for the Implementation Guide. If there are custom operations, they can be defined in the apiConfig object. Following is an example of how to add a custom operation:

operations: [
  ....
  {
      name: "custom-operation", // Custom operation name
      active: true // Whether the operation is active
      information: { // Optional information about the operation
          description: "Custom operation description",
          builtin: false,
      }
  }
]

2. Add the context related to the custom operation in the service.bal file. Following is an example of how to add a custom operation:

isolated resource function post fhir/r4/Specimen/\$custom\-operation(r4:FHIRContext fhirContext, Specimen procedure) returns r4:OperationOutcome|r4:FHIRError {
    return r4:createFHIRError("Not implemented", r4:ERROR, r4:INFORMATIONAL, httpStatusCode = http:STATUS_NOT_IMPLEMENTED);
}

Additionally, If you want to have a custom profile or a combination of profiles served from this same API template, you can add them to this FHIR API template. To add a custom profile, follow the steps below:

• Add the profile type to the aggregated resource type.
  • Example: public type Specimen r4:Specimen|<Other_Specimen_Profile>;
• Add the new profile URL in api_config.bal file. You need to add it as a string inside the profiles array.
  • Example:

    profiles: ["http://hl7.org/fhir/StructureDefinition/Specimen", "new_profile_url"]

This project is subject to the WSO2 Software License.