GNU Health/FHIR REST server

From Wikibooks, open books for an open world
Jump to navigation Jump to search

About FHIR and REST[edit | edit source]

Fast Healthcare Interoperability Resources (FHIR) is a standard for exchanging healthcare information electronically developed by HL7. For more information about FHIR, please see

Representational State Transfer (REST) is a software architecture style for scalable web services developed by the W3C Technical Architecture Group (TAG). REST based systems can be accessed over the Hypertext Transfer Protocol (HTTP), the same protocol that is used by Web browsers to request Web pages from and to send data to a Web server. For more information about REST, please see

Installation[edit | edit source]

The server requires Flask and a few of its addons. And, of course, a working GNU Health installation.

It is recommended to install the packages into a virtual environment using virtualenv.

Setup the environment (as the gnuhealth user):

$ pip install virtualenv                # Install virtualenv using python (may require root)
$ cd my_work_folder                     # Wherever you want to put the virtual environment folder
$ virtualenv -p /usr/bin/python2 venv   # Create the environment, with the Python 2.x interpreter
$ source venv/bin/activate              # Active the environment

Now install the packages using the requirements file:

$ pip install -r requirements.txt

Some of the packages (like pywebdav) are already installed on the system. However, it’s usually easier to administrate and debug the Flask server when working in a virtual environment.

More help with virtualenv.

Configuration[edit | edit source]

The server ships with a simple production config file. However, it needs to be edited.

TRYTON_DATABASE = ''    # GNU Health database
SERVER_NAME = ''        # Domain name of the server (e.g.,
SECRET_KEY = ''         # Set this value to a long and random string

There are other options available for Flask and its addons: * Flask * Flask-Login * Flask-Tryton * Flask-Restful * Flask-WTF

Security[edit | edit source]

Use TLS. Sensitive medical information must be protected and confidential.

By default, all FHIR endpoints except the Conformance statement require user authentication. The user authentication and access follows Tryton’s model, respecting model and field access rights.

The same credentials used to sign into GNU Health are used to access the FHIR REST server.

Running the Server[edit | edit source]

The server ships with a simple script ( in the server/ folder to run the server using Tornado.

The script expects itself to be located one directory level above the server/ folder. Consequently, move the script up one directory level. For example:

$ mv /example/base/server/ /example/base/

With the virtual environment activated and as the gnuhealth user, run the server.

$ python

However, most production servers use nginx, lighttpd, or apache in front of the Tornado server. For example, a common practice is to have nginx sit in front of multiple Tornado instances, acting as a load balancer, handling SSL, and serving static content (like images and common javascript). How to configure an nginx/lighttpd + tornado + flask setup is beyond this document, although it is not complicated, especially with nginx.

Troubleshooting[edit | edit source]

Cannot connect to database[edit | edit source]

Make sure you are running as the gnuhealth user.

Flask-Tryton should automatically find and parse the Tryton config file. If it is not found:

TRYTON_CONFIG = ''      # Set this to the path of the Tryton configuration file (e.g., '/weird/tryton/weird-tryton.conf')

No database with that name[edit | edit source]

This is related to the previous error, and occurs when Flask-Tryton cannot find the Tryton config file. Following the previous procedure should hopefully fix it.

Troubleshooting · Using the FHIR REST server