Home › Developer's Handbook ›

Online Booking API

Submitted by tony on Tue, 25/07/2017 - 09:43

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-bookings-api-2.0-SNAPSHOT.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.

 

Syndicate content