fhir-toolbox-go

FHIR® is the registered trademark of HL7® and is used with the permission of HL7®. Use of the FHIR trademark does not constitute endorsement of the contents of this repository by HL7®.

This project provides a set of packages for working with the HL7® FHIR® standard in Go. You only need to implement some interfaces and get a REST implementation out-of-the box.

This includes model types and interfaces modeling capabilities that you can use to build custom FHIR® servers.

While used in production at DAMEDIC, this project is still in its early days and the feature set is quite limit. We will add features as we require them. We welcome external contributions.

Features

• FHIR® model types with JSON and XML (un)marshalling

  • R4, R4B & R5

    use build tags r4, r4b or r5 for conditional compilation if you only need runtime support for specific versions

  • generated from the FHIR® specification

• Extensible REST API with capabilities modeled as interfaces
  • Capability detection by runtime reflection type assertion (see Capabilities)
    • alternatively: generic API for building wrappers
    • automatic CapabilityStatement generation
  • Interactions: read, search (adding the remaining interactions is definitely on the agenda)
  • Cursor-based pagination

Roadmap

• FHIRPath evaluation
• proper handling of _include and _revinclude
• resource validation
• remaining interactions (vread, create, update, patch, delete, history)

Getting Started

A quick "getting started" tutorial can be found in the ./examples/demo project.

Other Examples

You can find more examples in ./examples/. The mock example shows how to build custom FHIR® facades on top of legacy data sources using the capabilities API. The proxy example uses the generic API to forward all requests to another FHIR® server.

go run ./examples/proxy https://server.fire.ly/

This starts a simple mock-facade that forwards all requests to the HAPI test-server.

From another terminal, run

curl 'http://localhost/Patient/547'

or

curl 'http://localhost/Patient?_id=547'

to get a bundle.

Capabilities

Everything is designed around capabilities, represented by interfaces (e.g. PatientSearch). This flexible architecture allows different use cases, such as

• building FHIR® facades to legacy systems by implementing a custom backend
• using this library as a FHIR® client (by leveraging a - still to be build - REST backend)

Concrete vs. Generic API

The library provides two API styles. The concrete API:

func (a myAPI) ReadPatient(ctx context.Context, id string) (r4.Patient, capabilities.FHIRError) {}

func (a myAPI) SearchPatient(ctx context.Context, options search.Options) (search.Result, capabilities.FHIRError) {}

and the generic API:

func (a myAPI) Read(ctx context.Context, resourceType, id string) (r4.Patient, capabilities.FHIRError) {}

func (a myAPI) Search(ctx context.Context, resourceType string, options search.Options) (search.Result, capabilities.FHIRError) {}

You can implement your custom backend or client either way. The concrete API is ideal for building custom FHIR® facades where a limited set of resources is used (see ./examples/mock). The generic API is better suited for e.g. building FHIR® clients (see ./examples/proxy) or standalone FHIR® servers.

Interoperability

The capabilities/wrap package provides two wrapper functions to wrap a concrete into the generic API:

genericAPI := wrap.Generic[model.R4](concreteAPI)

and vice versa:

concreteAPI := wrap.ConcreteR4(genericAPI)

Packages

Scope

Everything part of the FHIR® specification is in scope of this project. However, we (DAMEDIC) do not strive for feature-completion. Instead we will only implement what we need for building our products. See Contribution below.

Contribution

We are happy to accept contributions. Bugfixes are always welcomed. For more elaborate features we appreciate commitment to maintain the contributed code.