REST API


The REST API allows developers to quickly and easily interact with PKB functionality in a programmatic way, including accessing patient medical records.

Specification

See here for auto-generated details of our REST operations.
  • All released versions of the API are shown -- for example, you'll see both "MeasurementService" (v0) and V1MeasurementService (v1) - we recommend always using the latest version you see.
  • Please ignore the "loggedInUser" parameter - you do not need to provide this!
  • You can review the objects you can pass in/out of the API, but there's no auto-gen docs on authentication; we've included full details on that process here.

Walkthrough

The following video details the process for making REST API calls authenticating as both a patient (client) and organization (site). Please note that in production only the refresh token is generated on first site invocation, please see here for a video outlining the refresh token authorization token swapping process. 

Here's a walk-through for using the docs to check how to add and fetch patient measurements.
  1. Check the API docs above for a V1 service that works with measurements under the "REST Resources" title. Found: V1MeasurementService
  2. Find the two calls currently available:
    1. /v1/measurements POST "Create a measurement."
      You can use an HTTP POST to send a JSON measurement to this endpoint to create a new measurement for the authenticated patient
    2. /v1/measurements/byType/{type} GET "Get the list of measurements stored for the given measurement type."
      You can send an HTTP GET to this endpoint to fetch the list of measurements for the type you provide
  3. The mount points suggested start with /rest/... but we want to use JSON, so instead of "/rest/v1/measurements" use "/json/v1/measurements"
  4. But what JSON to POST, and what are the types? Next you need the Measurement data model. Click the "Data Model" tab in the header (or from the home page)
  5. Click the "Measurement" data element. Comments on that page show the possible types (let's start with "weight").
    NOTE: the measurement types with alternative units (like "weightLbsOz") are for posting results only (they are auto-converted), not reading measurements.
  6. There's also example JSON on that page (showing the possible elements, though not sample values).
    When posting a new measurement, you would not supply the ID, and choose one of measureDate (JavaScript-style millisecond date) or measureDateISO (timestamp formatted to ISO 8601 standard). When fetching measurements, all of these will be populated.

Mass registration of patients

The API for decryption tokens allows mass registration of patients by letter-printing companies, patient kiosk vendors and hospital IT departments.

The faster an organisation registers patients the faster the return on investment. This API allows registering patients without needing face-to-face appointments. Instead the registration details for patients can go to each patient’s home using automatically generated letters from the institution’s existing database about the patient.

REST testing with Postman

There are many tools available to test REST APIs; we've had good experiences working with Postman, an app for Google Chrome.
http://www.getpostman.com/