CLWRota Technical Releases : XMLAPI Documentation
Index
- Introduction
- Notice about the use of data
- Formats
- Authentication
- Rate Limiting
- URL scheme
- HTTP response codes
- Example XML file
- Contact
Release version E: 08 April 2013
XMLAPI is the name given to the CLWRota application programming interface (API) for extracting department data in XML format.
This is a release of the XMLAPI documenation is for use by client departments and partner organisations. This version E document follows the previous release version D of 12 June 2013 following comments received by partners. Please note that some aspects of the API service are be subject to review.
Important changes to this version E include changes to rate limiting including limits per ip-address and the requirement for re-use of a login token. Jump to rate limiting section.
Notice about the use of data
The information provided here may be confidential. It is intended only for use by registered partners of anaesthetic departments who have written permission from the department to develop tools integrating the anaesthetic rota. It is the responsibility of any party intending to use data provided by the CLWRota system 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 system, including the XMLAPI.
The CLWRota APIs are provided without warranty, and may change from time-to-time. However, the CLWRota team will try and ensure backwards compatibility to the API where possible. Version information is provided with the results of each API call.
Formats
XMLAPI 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 support@erota.net.
Authentication
Authentication credentials to access the CLWRota XMLAPI should be provided by the department. Facilities to issue credentials are built into the CLWRota service.
The XMLAPI access credentials will provide an authentication token on successful login through a POST request, at https://example.clwrota.com/api/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 service is not overloaded by remote calls
The authentication token will allow:
- requests at a rate of no more than one request every 3 minutes
- up to 4 requests per token
- access for up to 10 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 – attemps to login again from the same ip address will fail.
URL scheme
Resources from CLWRota 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/api/auth/64628bbeba73/date/2012-01-30
| 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/api/auth/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
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
To view the latest version 0.4 version of the locations.xml page, please click here.
Previous locations xml versions:
Contact
To discuss the XMLAPI please contact the Campbell-Lange Workshop software team at software@erota.net.