Skip to content

Getting Started with popHealth API

petercyli edited this page Jul 20, 2017 · 23 revisions

A note of thanks to Christian Arias of Qualifacts for contributing the content of the this documentation.

Setting Up PopHealth For API Access

From popHealth configuration file (located in popHealth/config/popHealth.yml), set the “enable_csrf_for_apis” parameter to false

enable_csrf_for_apis: false

Be aware that this will disable CSRF for all API calls. This may be acceptable if your popHealth is hosted behind a firewall, but may be considered a security risk for a publicly facing instance.

Save the file and restart apache server and pophealth_delayed_worker process. The following examples use Postman application to access the popHealth REST interface.

How to Pass the Credentials to the API?

popHealth uses “Basic Auth”. Every service call requires user/password for authentication. Example: Retrieve a list of popHealth users - GET /api/admin/users. Note the setting for “Basic Auth” and the response in JSON. API Authentication

How to import a single patient XML file (Cat I or C-CDA) to a practice

Use POST /api/patients. Note that the setting for Authorization doesn’t change. The example below shows the “Body” setup for the Post call and the response indicating patient file imported. Load Patient File

How to import a (Cat I or C-CDA) patient zip file to a practice

Use POST /api/admin/patients. The example below shows the “Body” setup for the Post call and the response indicating patient file has been uploaded. Load Zip File

How to Start a Measure Calculation

Use POST /api/queries. The example below shows the “Body” setup for the Post call. Note that we used the “raw” with JSON(application/json) format to transmit the parameters.

  • measure_id - hqmf_id of the measure. You can find it from the following page in popHealth application - http://pophealth-demo.osehra.org/#admin/measures
  • effective_date - the end date of the reporting period. Use the epoch converter - https://www.epochconverter.com/ to convert dates from 12-31-2015
  • effective_start_date – the start date of the reporting period, i.e., 1-1-2015
  • providers – object id of the provider for “Practice OSEHRA”. This value can be obtained from a call to GET /api/practices. Start a Measure Calculation

How to Retrieve the Results of a Measure Calculation

Use GET /api/queries/:id. The :id in the GET call is the query cache id that was return from the previous call to start a measure calculation. It is first value from the returned JSON object. Note that the JSON response from the previous query indicates a status of "queued". How do we know that the measure calculation is completed? One way is to poll for the call to return a result. Another way, suggested by Christian Arias of Qualifacts, is to use a message broker (RabbitMQ) inside the execution of the PopHealth Jobs in order to notify either the job is done or not. During the execution of the job you send messages to a queue to notify the status of the job and calling application consumes this messages in order to know either the calculation is done or not. Retrieve Measure

How to Export the QRDA-3 XML Report for the Calculated Measure

Use GET /api/reports/*qrda_cat3.xml The parameters are passed in the GET call like query string. The parameter definitions are same as those used in the POST /api/queries to start a measure calculation. For example, /api/reports/*qrda_cat3.xml?measure_ids[]=40280381-51F0-825B-0152-22B98CFF181A&effective_date=1451621519&effective_start_date=1420088400&provider_id=58dcffae3df6211abeef93ef Retrieve QRDA-3 XML Report

Clone this wiki locally