GraphQL-FHIR

A secure GraphQL implementation for the HL7 FHIR specification based on the current implementation guide for GraphQL with FHIR and developed with Node.js and Express.

Prerequisites

You should have a basic understanding of working in Node.js and at least a basic understanding of what GraphQL is and how it works.

Getting Started

1. Installation

   git clone https://github.com/Asymmetrik/graphql-fhir.git
   cd graphql-fhir
   yarn install

2. Start a local dev server

   # For development
   yarn nodemon

3. View http://localhost:3000/3_0_1/$graphiql to explore the available queries and mutations in the graphiql interface. The standard graphql endpoint is available at http://localhost:3000/3_0_1/$graphql.

What's next

See our Frequently Asked Questions for explanations on how to configure the server, connect to an actual database, setup authentication, and more. You can also read up on the project structure under the Architecture section if you are curious about that kind of thing. If you are want to know about our future plans, see our Roadmap. If you have any other questions, please ask them on StackOverflow with the tag graphql-fhir.

Frequently Asked Questions

• What yarn(or npm) commands are available?
• What server configurations are available and how do I use them?
• Do you support authentication?
• How and where do I write GraphQL resolvers?
• What database's do you support and how do I connect to a database
• How are errors supposed to be handled?
• How do I configure which resources I support and with what capabilities?
• Can I do metadata queries?
• How do I ask for specific fields in a response when the response is a bundle (or some other union of types)?

Architecture

We designed this project in the way that we did so we can support multiple versions simultaneously and add new versions very quickly. Everything in src/resources is generated by an internal tool that reads Structure Definitions downloaded from the official FHIR website. The tool output's schemas, inputs, parameter files, custom scalars, and profile endpoints, which includes files used to register queries and mutations with the server as well as resolvers.

If you decide to use this server, you will rarely need to modify code in src/resources except for code in the profiles, since this is where you add resolver logic and configure which profiles you want to support.

The folder structure for the project looks like this:

src
| - config.js
| # Contains server and version configuration 
| - index.js
| # Entry to the application
| - src/lib
| # Contains custom libs we use, server, logger's, etc
| - src/middleware
| # Custom express middleware
| - src/scripts
| # Scripts for local development and testing.
| - src/utils
| # Various utilities used throughout the application
| - src/resources
| # All the code in here is auto generated for each version
|  | - 3_0_1
|  | # This directory contains all the 3_0_1 logic
|  |  | - inputs
|  |  | # Contains all input schemas for mutations
|  |  | - parameters
|  |  | # Defines what arguments can be provided to search operations.
|  |  | - scalars
|  |  | # Contains some custom FHIR types.
|  |  | - schemas
|  |  |  # Defines all the output schemas.
|  |  | - profiles
|  |  |  # Contains all the configurable profiles for GraphQL.
|  |  |  | - patient # or any other resource for that matter
|  |  |  |  | - index.js
|  |  |  |  | # File used to register capabilities with the server
|  |  |  |  | - mutation.js
|  |  |  |  | # Mutations configuration. Auto-Generated and should not modify
|  |  |  |  | - query.js
|  |  |  |  | # Query configuration. Auto-Generated and should not modify 
|  |  |  |  | - resolver.js
|  |  |  |  | # Contains placeholders, your logic to query your backend goes here.

Roadmap

• [x] Authentication Initializers and passport support
• [x] Better documentation on setup and configurations
• [x] Change return format for ResourceList queries to a FHIR Bundle instead of a GraphQLList
• [ ] Implementation guides and demos
• [ ] Support for more resources
  • [ ] USCore resources.
• [ ] Support for more versions
  • [x] DSTU2 (1.0.2).
  • [x] STU3 (3.0.1).
  • [x] R4
• [ ] Work with community to continue to establish best practices for FHIR with GraphQL and implement them here.

Contributing

Please see CONTRIBUTING.md for more details regarding contributing issues or code.

License

graphql-fhir is MIT licensed.