Index

Release version G: January 2018

PublicAPI is the name given to the application programming interface (API) for extracting department data from CLWRota or Medirota in XML format.

This release of the PublicAPI documentation is intended for use by client departments and partner organisations. This version F document follows the previous release version F of November 2017, following the expansion of the API to Medirota. Please note that some aspects of the API service are subject to review.

Important changes to version G include updating the rate limiting information to match the defaults in production.

Notice about the use of data

The information provided here may be confidential. It is intended only for use by registered partners of clinical departments who have written permission from the department to develop tools integrating the relevant rota(s). It is the responsibility of any party intending to use the data provided by CLWRota and Medirota services that confidentiality of data and personal details (as defined by the Data Protection Act) are protected and that, where necessary, permission has been sought by the department and individuals concerned or identified. Formal agreements should be in place between the department and any consumer of data provided through the CLWRota and Medirota services, including the PublicAPI.

The CLWRota and Medirota APIs are provided without warranty, and may change from time-to-time. However, the Rotamap team will try and ensure backwards compatibility to the API where possible. Version information is provided with the results of each API call.

Formats

PublicAPI output is presently shown in XML format. We hope to provide the output in json format in future too. Please let us know if you are interested in receiving data in json format by emailing the software team at software@rotamap.net.

Authentication

Authentication credentials to access the CLWRota or Medirota PublicAPI should be provided by the department. Facilities to issue credentials are built into the CLWRota and Medirota services.

The PublicAPI access credentials will provide an authentication token on successful login through a POST request, at https://example.clwrota.com/publicapi/login/ or https://example.medirota.com/publicapi/login/. This token has to be renewed every 10 minutes and renewal should be automated.

Rate Limiting

The rate limiting controls are designed to ensure that the CLWRota and Medirota services are not overloaded by remote calls

The authentication token will allow:

  • requests at a rate of no more than one request every 20 seconds
  • up to 50 requests per token
  • access for up to 20 minutes

After the token has expired the login process must be repeated in order to access the resources. However the token must be re-used for subsequent calls within the 10 minute window – attempts to login again from the same ip address will fail.

Leave requests introduction

The leave requests component of Rotamap's services provides an approval queue for clinician's leave. It will be helpful to have a general understanding of how leave works when querying the API.

Leave may be of various types, such as Annual, Study, Sick, Parental, Professional, Compassionate, and other common types, or any number of department-specified leave types. Department-specific rules govern settings such as the allowable duration of leave, how far in the future it may be booked, and whether annual leave may be auto-approved through the system.

Other important settings include those for units (day or session based leave), whether a common department leave year or individual leave years are used for managing allowances, the default sessions over which leave is booked (of am, pm, evening and night) and whether bookings over the evenings and weekends count against leave. An important setting determines if leave costs are calculated based on missed sessions -- when the individual was due to work -- or on an absolute leave span basis.

Example GET workflow for leave requests and the PublicAPI

An external system may use the PublicAPI to periodically collect leave information once they have reached the "approved" end point. In this example, the external system picks up study leave requests with completed expenses information once they have been approved. These requests are recorded in the external system without subsequent calls to the Rotamap system.

  • Clinician submits a study leave request for approval on the Rotamap system, entering the relevant estimated costs for course fees, travel costs and subsistence.
  • If leave request can be supported by department and if clinician has sufficient leave, the department leave administrator approves the study leave on the Rotamap system.
  • The external system picks up all `approved' study leave through a periodic GET call.
  • The costs associated with the study leave are approved or rejected by the relevant HR or Medical Education team on the external system.
  • The clinician decides to request that the study leave be cancelled in the Rotamap system if costs are rejected and/or the study leave is no longer required.
  • The department leave administrator cancels the leave.
  • The external system picks up `cancelled' study leave through a periodic GET call and updates its own records appropriately.

URL scheme

Resources from CLWRota or Medirota via GET requests may be retrieved through the API through the following REST oriented url schemes each with a base of
https://ex.clwrota.com/publicapi/64628bbeba73/date/2012-01-30

It is important to note that the API has moved from /xmlapi/ to /publicapi/. We intend to deprecate the old url by the end of 2017.

1. locations /locations
2. oncalls /oncalls
3. people /people
4. consultants /consultants
5. trainees /trainees

Note that data is retrieved on a per-day basis.

The oncalls GET request will provide a subset of the locations call, in much the same way as the consultants and trainees calls will provide subsets of the information provided by the people call.

At present only the locations and oncalls calls are to be provided.

Additional filters may be provided after a ? filter at the end of the url, for example ?session=am to filter the results to only show only morning sessions. It may be useful to incorporate an updated-since=<timestamp> facility to only retrieve sessions updated since a particular date/time.

Filters to be implemented, shown with a base url of
https://ex.clwrota.com/publicapi/64628bbeba73/date/2012-01-30/locations/:

Filter Parameters Example
1. filter by session am|pm|eve|night ?session=am
2. filter by location group #id ?location-group=34
3. filter by person group #id ?person-group=77
4. filter by recent changes #timestamp ?changed-since=2012-06-01 10:10:02

Please note that #id values should be string-formatted integers. Timestamps should be in ISO 8601 format, for example 2012-04-05T14:30

Leave URL scheme

The base leave related API calls are as follows:

1. leave locations /leave/locations
2. leave queue status listing /leave/list/<status>
3. leave detail /leave/id

Leave queue listings

There are two variants of the listing, one by queue type, the other by location (or leave variety) type.

The first variant provides list of leave requests by queue type, optionally filtered by leave location (such as 'Annual Leave' or 'Study Leave'), status, such as 'approved' or 'cancelled' and/or other parameters such as markers. It may be necessary to allow filtering to exclude leave before a certain date to reduce the return set, or only show leave requests added or modified after a certain timestamp.

Path /leave/list/<status>
[?location=<uuid>]
[?current_only=true|false]
[?marker=<markerid>]
[?since=<timestamp>]
[?ioffset=<number>]
Methods GET
Function list leave requests
Params location filter: e.g. to show only 'Study Leave'
current_only filter: false for older records
marker: filter by marker id
since: show records updated since timestamp <since>
ioffset: offset the results by <number> records
Response type application/xml
Authentication required

The location filter requires the uuid of the leave location, which can be determined through the /leave/locations call.

The current_only filter is set to 'true' by default. This means that only records that either overlap the current date or are in the future are returned. Set this to 'false' for historical records.

Note that by default no more than 250 leave requests will be returned. To retrieve, for example, the following set of records, use ?ioffset=250.

HTTP response codes

The following HTTP response codes will be returned:

Response code Text Meaning
200 OK Success
304 Not Modified There is no new data to return
400 Bad Request Invalid request
401 Unauthorised Login failed or the login credentials have expired
403 Forbidden Access to the specified resource is not allowed, possibly because of the request limit being exceeded
404 Not found Resource not found
420 Rate Limited A rate limit has been exceeded
500 Service problem There is a problem with our service. Please let us know.
502 Bad Gateway The service is down or being upgraded

Example XML file

We no longer provide example xml files as the api is self-documenting after login.

Contact

To discuss the PublicAPI please contact the Rotamap software team at software@rotamap.net.