Getting Started with popHealth API
A note of thanks to Christian Arias of Qualifacts for contributing the content of this documentation.
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.
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.
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.
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.
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.worldvista.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 the provider_id value returned from a call to GET /api/practices.
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.
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
