Online Booking API V1

Submitted by tanderson on Wed, 13/02/2019 - 10:09

The OpenVPMS Booking API is a JSON API for making appointments in OpenVPMS. This API first appears in OpenVPMS 2.0.

The following assumes:

OpenVPMS is accessed at http://localhost:8080/openvpms
a user with login name 'sample' and password 'changeit' exists, and has been assigned the Online Booking role

The openvpms-booking-api-v1.zip contains API documentation generated by Enunciate. Extract and browse from index.html.

You can also get an overview by browsing http://localhost:8080/openvpms/ws/booking/v1/application.wadl

Locations

To get the locations:

> curl -i -u sample:changeit http://localhost:8080/openvpms/ws/booking/v1/locations
HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
Content-Type: application/json
Content-Length: 126
Date: Tue, 25 Jul 2017 03:33:24 GMT

[{"id":99,"name":"Branch Clinic","timeZone":"Australia/Sydney"},
 {"id":113,"name":"Main Clinic","timeZone":"Australia/Sydney"}]

Notes:

for a location to be returned, its Online Booking flag must be ticked.

To get the schedules available at a location:

> curl -i -u sample:changeit http://localhost:8080/openvpms/ws/booking/v1/locations/113/schedules
HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
Content-Type: application/json
Content-Length: 117
Date: Tue, 25 Jul 2017 03:35:34 GMT

[{"id":144,"name":"Main Appointment Schedule","slotSize":15},
 {"id":130,"name":"Main Surgery Schedule","slotSize":30}]

For a schedule to be returned, its Online Booking flag must be ticked.

Appointment Types

To get the appointment types applicable to a schedule:

> curl -u sample:changeit http://localhost:8080/openvpms/ws/booking/v1/schedules/144/appointmentTypes
[{"id":62,"name":"New Patient","slots":2},
 {"id":52,"name":"Long Consult","slots":2},
 {"id":50,"name":"Standard Consult","slots":1},
 {"id":46,"name":"Short Consult","slots":1}]

Notes:

the same appointment type may be used by multiple schedules, each with a different slot size
for an appointment type to be returned, its Online Booking flag must be ticked.

Free/Busy

A number of methods are provided to get free and busy times:

> curl -u sample:changeit 'http://localhost:8080/openvpms/ws/booking/v1/schedules/144/free?from=2016-05-15T00:00:00%2B10:00&to=2016-05-16T00:00:00%2B10:00'
[{"start":"2016-05-15T10:30:00.000+10:00","end":"2016-05-15T11:00:00.000+10:00"},
 {"start":"2016-05-15T11:30:00.000+10:00","end":"2016-05-15T17:30:00.000+10:00"}]

> curl -u sample:changeit 'http://localhost:8080/openvpms/ws/booking/v1/schedules/144/busy?from=2016-05-15T00:00:00%2B10:00&to=2016-05-16T00:00:00%2B10:00'
[{"start":"2016-05-15T09:00:00.000+10:00","end":"2016-05-15T10:30:00.000+10:00"},
 {"start":"2016-05-15T11:00:00.000+10:00","end":"2016-05-15T11:30:00.000+10:00"}]

If you want both free and busy times, its more efficient to do a single call:

> curl -u sample:changeit 'http://localhost:8080/openvpms/ws/booking/v1/schedules/144/freebusy?from=2016-05-15T00:00:00%2B10:00&to=2016-05-16T00:00:00%2B10:00'
{"free":[{"start":"2016-05-15T10:30:00.000+10:00","end":"2016-05-15T11:00:00.000+10:00"},  {"start":"2016-05-15T11:30:00.000+10:00","end":"2016-05-15T17:30:00.000+10:00"}],
 "busy":[{"start":"2016-05-15T09:00:00.000+10:00","end":"2016-05-15T10:30:00.000+10:00"},
              {"start":"2016-05-15T11:00:00.000+10:00","end":"2016-05-15T11:30:00.000+10:00"}]}

To return the free and busy times in slots, specify &slots=true e.g.:

> curl -u sample:changeit 'http://localhost:8080/openvpms/ws/booking/v1/schedules/144/free?from=2016-05-15T00:00:00%2B10:00&to=2016-05-16T00:00:00%2B10:00&slots=true'
[{"start":"2016-05-15T10:00:00.000+10:00","end":"2016-05-15T10:15:00.000+10:00"},
{"start":"2016-05-15T10:15:00.000+10:00","end":"2016-05-15T10:30:00.000+10:00"},
{"start":"2016-05-15T10:30:00.000+10:00","end":"2016-05-15T10:45:00.000+10:00"},
{"start":"2016-05-15T10:45:00.000+10:00","end":"2016-05-15T11:00:00.000+10:00"},
{"start":"2016-05-15T11:30:00.000+10:00","end":"2016-05-15T11:45:00.000+10:00"},
{"start":"2016-05-15T11:45:00.000+10:00","end":"2016-05-15T12:00:00.000+10:00"},
{"start":"2016-05-15T12:00:00.000+10:00","end":"2016-05-15T12:15:00.000+10:00"},
{"start":"2016-05-15T12:15:00.000+10:00","end":"2016-05-15T12:30:00.000+10:00"},
{"start":"2016-05-15T12:30:00.000+10:00","end":"2016-05-15T12:45:00.000+10:00"},
{"start":"2016-05-15T12:45:00.000+10:00","end":"2016-05-15T13:00:00.000+10:00"},
{"start":"2016-05-15T13:00:00.000+10:00","end":"2016-05-15T13:15:00.000+10:00"},
{"start":"2016-05-15T13:15:00.000+10:00","end":"2016-05-15T13:30:00.000+10:00"},
{"start":"2016-05-15T13:30:00.000+10:00","end":"2016-05-15T13:45:00.000+10:00"},
{"start":"2016-05-15T13:45:00.000+10:00","end":"2016-05-15T14:00:00.000+10:00"},
{"start":"2016-05-15T14:00:00.000+10:00","end":"2016-05-15T14:15:00.000+10:00"},
{"start":"2016-05-15T14:15:00.000+10:00","end":"2016-05-15T14:30:00.000+10:00"},
{"start":"2016-05-15T14:30:00.000+10:00","end":"2016-05-15T14:45:00.000+10:00"},
{"start":"2016-05-15T14:45:00.000+10:00","end":"2016-05-15T15:00:00.000+10:00"},
{"start":"2016-05-15T15:00:00.000+10:00","end":"2016-05-15T15:15:00.000+10:00"},
{"start":"2016-05-15T15:15:00.000+10:00","end":"2016-05-15T15:30:00.000+10:00"},
{"start":"2016-05-15T15:30:00.000+10:00","end":"2016-05-15T15:45:00.000+10:00"},
{"start":"2016-05-15T15:45:00.000+10:00","end":"2016-05-15T16:00:00.000+10:00"},
{"start":"2016-05-15T16:00:00.000+10:00","end":"2016-05-15T16:15:00.000+10:00"},
{"start":"2016-05-15T16:15:00.000+10:00","end":"2016-05-15T16:30:00.000+10:00"},
{"start":"2016-05-15T16:30:00.000+10:00","end":"2016-05-15T16:45:00.000+10:00"},
{"start":"2016-05-15T16:45:00.000+10:00","end":"2016-05-15T17:00:00.000+10:00"},
{"start":"2016-05-15T17:00:00.000+10:00","end":"2016-05-15T17:15:00.000+10:00"},
{"start":"2016-05-15T17:15:00.000+10:00","end":"2016-05-15T17:30:00.000+10:00"}]

Submitting Bookings

> curl -u sample:changeit -H "Content-Type: application/json" --data @booking.json http://localhost:8080/openvpms/ws/booking/v1/bookings

Where booking.json is a file containing:

{
  "location": 113,
  "schedule": 144,
  "appointmentType": 50,
  "start": "2016-05-15T10:30:00.000+10:00",
  "end": "2016-05-15T11:00:00.000+10:00",
  "title": "Ms",
  "firstName": "Judith",
  "lastName": "Bourke",
  "mobile": "0418976543",
  "patientName": "Muffett"
}

Notes:

the email and phone attributes can be specified as well.
a booking customer is considered a match if its firstName and lastName are equal to an OpenVPMS customer, ignoring case, and at least one of the 3 contacts are present.
the reference returned is a concatenation of the appointment identifier, customer identifier and UUID. This is to:
- make it harder to retrieve/cancel bookings not made through the API
- prevent retrieval of appointments subsequently assigned to another customer

Retrieving Bookings

> curl -u sample:changeit http://localhost:8080/openvpms/ws/booking/v1/bookings/603:3:be08f3c6-1afb-11e6-be41-3dbaef689d97

Notes:

the mobile, phone and email submitted with the request are not stored; the values returned are those associated with the existing customer
the notes aren't returned as these may have been updated since the booking was made and contain information that shouldn't be disclosed

Cancelling Bookings

> curl -X DELETE -u sample:changeit http://localhost:8080/openvpms/ws/booking/v1/bookings/391:a98f02c9-1a4b-...

Notes:

bookings can only be cancelled while their corresponding appointment is pending
once cancelled, bookings cannot be retrieved

Security

There are a number of security considerations to be aware of:

an OpenVPMS user account is required to make online bookings. This should be a restricted account that only has the authorities required to make online bookings.
This can be done by creating a user that only has the Online Booking role assigned.
the OpenVPMS web application should not be exposed to the wider internet to allow external providers to connect. Restricted access can be provided through a VPN, IP filtering, and/or URL filtering. For the purposes of online booking, only the:
/openvpms/ws/booking
URL should be exposed.