API calls for discussion

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


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