Docs : Public API Documentation

Public API Index

April 2022

Introduction
Notice about the use of data
Formats
Authentication
Rate Limiting
Leave requests introduction
Example GET workflow for leave
URL scheme
Leave URL scheme
Leave queue listing
Bid offers URL scheme
Bid offers listing
Person rota listing
Groups listing
HTTP response codes
Example XML file
Contact

Release version K: April 2022

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 includes an addition to the leave URL scheme which details how to call leave requests over a date range. Please note that some aspects of the API service are subject to review.

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 Rotamap services that confidentiality of data and personal details (as defined by the applicable data protection laws) 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 Rotamap services, including the PublicAPI.

Rotamap service 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 mostly shown in XML format. JSON format is additionally available for bid offers. We hope to provide more 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/. For example, using the cURL command-line tool this might look something like:

curl -X POST -d 'username=example@example.net' -d 'password=Examplepw1' https://example.medirota.com/publicapi/login/

The token has to be renewed every 10 minutes and renewal should be automated.

Paths	/login/
Methods	POST
Form data	username password
Function	return authentication token
Response type	application/xml or application/json

If this endpoint is called with an "Accept: application/json" header, then it will return the data in a JSON format as opposed to XML.

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

A list of active staff profiles from CLWRota or Medirota via a GET request can be retrieved with a base url of
https://ex.clwrota.com/publicapi/<token>/people/list/

Additional filters may be provided after a ? as follows:

Filter	Parameters	Example
1. filter by person group	#id	?person_group=77
2. show disabled profiles	true	?show_disabled=true

All other 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/<token>/date/2012-01-30

1. locations	/locations
2. oncalls	/oncalls
3. rota	/rota

Note that data for oncalls and rota can be retrieved for a day, week or date range.

The oncalls GET request will provide a subset of the locations 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 changed_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/<token>/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-05 14:30:10

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 listing

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>] [?from_date=<date>&to_date=<date>]
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 date range: show leave requests falling between two dates.
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.

Bid offers URL scheme

Bid offers are uncovered sessions on CLWRota and Medirota that have been offered out to request cover.

The base bid offer related API calls are as follows:

1. bid offers	/bid_offers/
2. single bid offer	/bid_offer/<id>

Bid offers listing

The first above call can return many bid offers, optionally filtered via a changed-since timestamp, and the second will return a single bid offer from a given bid offer ID.

If either are called with an "Accept: application/json" header, then they will return the data in a JSON format as opposed to XML.

Paths	/bid_offers/ [?since=<timestamp>] /bid_offer/<id>
Methods	GET
Function	list bid offer(s)
Response type	application/xml or application/json
Authentication	required

Person rota listing

This endpoint provides a person rota output. This is unnested rota data to describe what each person is doing over a provided date range. It can be filtered by a location group and/or a person group.

If the below endpoint is called with an "Accept: application/json" header, then it will return the data in a JSON format as opposed to XML.

Path	/person_rota/ [?from_date=<date>&to_date=<date>] *required [?filter_location_group=<id>] [?filter_person_group=<id>]
Methods	GET
Function	list person rota
Params	date range: only show rota data failing between these dates filter_location_group: only show rota data occuring in locations contained within this group filter_person_group: only show rota data for people contained within this group
Response type	application/xml or application/json
Authentication	required

Groups listing

This endpoint provides a list of location or person groups. It can be called with a parameter to list location groups or person groups.