API calls for discussion
03 March 2019
Rotamap has provided a public API for rota and leave data for several years, with integrations built by several providers and client Trusts. This API is in REST/XML format. For more information please read our PublicAPI documentation.
What follows is a sketch API to allow a group of providers to provide the job planning and rostering requirements of a Trust in an interoperable manner. The sketch is oriented in part towards NHSi's concept of a "System" representing the composite of services used by a Trust.
We are keen to encourage collaboration with other providers. Consequently, the API sketch contents of this page are shared under the Creative Commons Attribution 4.0 International License or any later version. We hope to publish future versions of this API in OpenAPI 3.0.2 format under the same or a related Creative Commons License, possibly on Github.
Please email systemapi@rotamap.net to make comments or to initiate a discussion.
Index
- Introduction
- General structure
- API root
- System API calls
- Rostering API calls
- Leave API calls
- Junior Doctor API calls
- Job Planning API calls
An API model for an NHS Trust "System"
Rotamap Ltd.
03 Mar : Version 0.0.5 : (add rota person activity summary)
03 Mar : Version 0.0.4 : (rework system methods)
27 Feb : Version 0.0.3 : (expand calls, add methods)
25 Feb : Version 0.0.2 : (reformat intro)
25 Feb : Version 0.0.1 : (first version)
Introduction
The following sets out a API model for a "System" of composite services provided both to and by an NHS Trust.
The System spans rostering for all clinicians, job planning and junior doctor rotas. Other elements, such as staff bank agency integration, leave and expenses are also covered.
This API can be offered in part by providers as part of a total Trust
system. The API provides a common way of describing the staff groups
the provider's services cover and the functionality their service or
services provide. In this model, all providers will be expected to
implement the /system API calls to advertise the scope of their
services to the Trust, thereby helping describing their contribution to
the System.
Coverage of the System is a matter for a Trust and its contracting parties.
This model does not cover provider-to-provider authentication and authorization and permission scopes. It is assumed that Trusts will coordinate provider-to-provider and provider-to-Trust authorization. We assume OAUTH2/RFC 6749 protocols will be used, perhaps with (section 4.3) "Resource Owner" type grants.
This API proposal seeks to make data receiving and data writing operations as simple and legible as possible. Consequently, complex issues such as the verification of written data should be dealt with by the receiving application, and is not considered a subject of this model.
General structure
/system prefixed API paths are common to all provider services and
provide registers for integration with other providers and together can
provide the description of a total System for a Trust. Trusts may
declare certain providers' /system registers as authoritative.
/rotas prefixed API paths are for all rostering services
/leave prefixed API paths are for all leave-related services,
including expenses
/jobplanning prefixed API paths are for all job planning-related
service calls
/juniordoctor prefixed API paths are for all junior doctor-related
service calls, although most of these are similar to the /rotas calls.
API root
/ GET
The current timestamp
A pointer to /system
System API calls
/system GET
information about this system the provider details array of contact type
/system/services GET
information about the services provided in this system returns array of service mark read/writeability of calling service for each endpoint
/system/organization GET
basic information about the organisation array of contact type
/system/organization/structure GET
returns array of ou (organizational units) describing hierarchy (simple version of LDAP tree) consider nested hierarchy instead
/system/people GET POST
array of person in system nested by type types of people described by openapi polymorphic types based on ESR base entity support query by type, by any unique id person attributes allow arrays of ou assignments in time person attributes allow arrays of role in time
/system/roles GET
array of role
/system/sites GET
array of site for example, hospital sites
/system/places GET
array of place real, general, notional and ancillary places may be registered for example, 'Theatre 1', 'Annual Leave'
/system/agencies GET
array of agency, recording staff bank agencies registered with this System
/system/registers GET
other registers
Rostering API calls
/rotas GET
array of rota by OU
shows read/write permissions for the reader
/rotas/byplace/{rotaid} GET
map of rotabyplace, by default by week, for current week
may be planned or actual events, or a combination
/rotas/byrequirement/{rotaid} GET
map of requirementsbyplace, by default by week, for current week
may be planned or actual rolerequirements, or a combination
/rotas/byperson/{personid} GET
map of rotabyperson, by default by week, for current week
may be planned or actual personevents, or a combination
/rotas/byperson/{personid}/summary GET
map of rotasummarybyperson, by default the current financial year
summary of planned or actual activity
suitable for jobplanning comparison
/rotas/{rotaid} POST
write a person or role requirement event (planned or actual) into the specified rota at the specified place
/rotas/{rotaid}/event/{eventid} PUT, DELETE
update or delete a personevent or rolerequirementevent
updates may include flags such as accepted | rejected | submitted
Leave API calls
/leave/person/{personid} GET
summary of all leavesummary for a person, by default for coming year
include status submitted | approved | rejected
/leave/ POST
add a leave record for a person
/leave/{leaveid} GET, PUT, DELETE
detailed leave record for a person
includes array of expense record
view, edit or delete a leave record for a person
/leave/{leaveid}/expense POST
add an expense record for a leave record
/leave/{leaveid}/expense/{expenseid} GET, PUT, DELETE
view, edit or delete an expense record for a leave record
Junior Doctor API calls
/juniordoctor/rotas GET
array of junior doctor rota by OU
shows read/write permissions for the reader
/juniordoctor/rotas/byplace/{rotaid} GET
map of rotabyplace, by default by week, for current week
may be planned or actual events, or a combination
/juniordoctor/rotas/byrequirement/{rotaid} GET
map of requirementsbyplace, by default by week, for current week
may be planned or actual rolerequirements, or a combination
/juniordoctor/rotas/byperson/{personid} GET
map of rotabyperson, by default by week, for current week
may be planned or actual personevents, or a combination
/juniordoctor/rotas/{rotaid} POST
write a junior doctor person or role requirement event (planned or actual) into the specified rota at the specified place
/juniordoctor/rotas/{rotaid}/event/{eventid} PUT, DELETE
update or delete a personevent or rolerequirementevent
updates may include flags such as accepted | rejected | submitted
Job Planning API calls
/jobplans GET
array of current jobplanprecis with status by OU
/jobplans/byperson/{personid} GET
array of jobplansummary by person with status
/jobplans/{jobplanid}
array of plannedactivity
details of jobplansummary
array of jobplansignoff
/jobplans/{personid} POST
create a jobplan for person
/jobplans/{jobplanid} POST
create a jobplan plannedactivity for person
/jobplans/{jobplanid} GET, PUT, DELETE
view, edit or delete a jobplan plannedactivity for person
/jobplans/{jobplanid}/signoff POST
create a signoff for a jobplan
/jobplans/{jobplanid}/signoff/{signoffid} GET, PUT, DELETE
view, update or delete a signoff for a jobplan