API Guide
Status: Work In Progress
- Introduction
- Definitions
- Architecture of the API
-
Uses cases with guidance
- Receive a Requested Booking and act upon it
- Search for a Person
- Create a booking
- Redirect in-progress move
- (Log a journey)
- (Allocations)
- ...
This is a guide to using the Book A Secure Move API.
This API is part of the solution built in order to create and manage booking requests to transfer people between locations involved in the justice system. In particular, this API allows suppliers to interact with the booking system, and supports the front-end application (see https://github.com/ministryofjustice/hmpps-book-secure-move-frontend).
This guide is an explanation of how to use the API to accomplish supplier activities
This guide is aimed at move suppliers, and in particular the teams responsible for integrating with the Book a Secure Move API
The first few sections of this guide should be read and understood up to the use cases. The use cases will be added to over time, and so readers may choose to only read the detail of each use case at the point of implementation.
Swagger allows you to describe the structure of your APIs so that machines can read them.
The Swagger spec for the current version of the Book a Secure Move API can be found at:- https://api.bookasecuremove.service.justice.gov.uk/api-docs/index.html.
This spec covers the fine-grained detail of each of the methods and data structures available in the API. Consumers are not necessarily expected to implement all of these. The Swagger spec is instead best used as a reference for those methods and data structures that are required to fulfil a need.
There are several webhooks that can be configured as part of Book a Secure Move. They are documented here - Webhooks
The source code for the Book a Secure Move API is publicly available on GitHub at this URL: https://github.com/ministryofjustice/hmpps-book-secure-move-api.
Please see the Readme in that repository for more information.
The whole service is designed around moving people safely. The people in this context may be prisoners, detainees, children or a young person. In this guide, we will refer to Person (plural either People or Persons) to refer to whichever of these is being moved.
The unit of reference when booking a location transfer for a Person will be a Move. This could be one of a number of different types of Move (for example Prison to Court, Court to Prison, Prison to Prison, and others), and encapsulates the purpose for the move, as well as the intended start and end location, regardless of intermediate stops. A Person may have multiple Moves on the same day - especially if they are for a different purpose. It is also possible that a Move could last for longer than a single day if it starts late at night and overnight lodging is necessary.
A Journey is a unit of travel from one location to another that forms a part of a Move. There will always be at least one Journey as part of a completed Move, but in some cases more. For example, a Move that takes place over two days will often have a Journey from the pickup location to a holding location, followed by another Journey from the holding location to the destination location.
Each of the Moves and Journeys within the service have a start point and an end point. These are Locations. In this service, every Location is pre-defined (with the exception of some unplanned emergencies), where the reference data comes from NOMIS. Locations are normally Police Stations (Custody Suites), Prisons, Courts, Secure Children's Homes (SCH), Secure Training Centres (STCs) and Young Offender Institutions (YOIs)
If a Person has multiple Moves over time, the information about that Person may change. In particular, new or changed risks or assessments may become apparent. In order to represent the specific information relevant to a particular Move, we have the concept of a Profile. A Profile is a subset of information about a Person that is related to a particular Move. A Move will always be linked to a single Profile, but it is possible for a Profile to be linked to several Moves (for example, if a person has two Moves on the same day and nothing changes between them).
As part of a Move or a Journey, there may be a need to record that something has happened, or that something has changed. These are captured in this service as Events.
** not yet handled
** to be completed
** not yet handled
** not sure if needed - check after diagram present
There are two elements of the API that have security requirements - the Book a Secure Move API itself, and (optionally) the Webhooks. For Webhook security, see Webhooks.
The API is secured using an API key. These are generated by MoJ, and distributed to suppliers as required. The API key itself is then hashed by MoJ and the hash is stored. It is then not possible to recover the API key from the hash.
For production environments, API keys must be transferred securely. The recommendation is that the suppliers generate a GPG public-private key pair, then send the public key to MoJ, who will generate a securely random string, encrypt with the public key, and send the encrypted key back to the supplier. In addition, MoJ will create a secure hash from the API key and store this. The supplier will decrypt the key using their private key, and it will be sent in an authorisation header. MoJ will take the hash of the sent key and compare it to the one on file.
(For production webhook credentials, it would be appropriate to use a similar mechanism).
Supplier systems will authenticate with the APIs using OAuth2.
Each Supplier will be given
- A client ID
- A client secret
These will be sent to the authorization server, and exchanged for a token, using the OAuth2 client credentials grant type:
POST /oauth/token HTTP/1.1
Host: pecs-platform.example.com
grant_type=client_credentials
&client_id=xxxxxxxxxx
&client_secret=xxxxxxxxxxThe token will be supplied with an expiry time (60 minutes in this example), after which a new token must be requested.
HTTP/1.1 200 OK
Content-Type: application/json
{
"access_token": "MTQ0NjJkZmQ5OTM2NDE1ZTZjNGZmZjI3",
"token_type": "bearer",
"expires_in": 3600
}This token can then be used as a Bearer token to authorize requests to the API.
GET /ping HTTP/1.1
Host: pecs-platform.example.com
Authorization: Bearer MTQ0NjJkZmQ5OTM2NDE1ZTZjNGZmZjI3If the supplied credentials are invalid, the OAuth2 spec requires that we return the following response.
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"error":"invalid_client"
}Provision will be made to allow these credentials to be replaced and rotated.
This will mean that two Client Secrets may be in use at the same time, and both can be used to create a token.
Once the Supplier’s systems have been updated to use the new Client Secret, the old Client Secret will be disabled, at which point it will no longer work to create a Token.
Once the Token expires, it will give a “401 Unauthorized” error
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"errors": [
{
"status": "401",
"title": "unauthorized",
"detail": "Token invalid"
}
]
}The Supplier’s System should now request a new Token.
Supplier Systems must use secure mechanisms to authenticate and authorise all end users.
to be completed
There is a separation between the Authentication APIs and the PECS APIs.
The Authentication endpoints use standard OAuth2, and therefore use the standard JSON content type.
Content-Type: application/json
The PECS API endpoints follow the JSON:API 1.0 spec (https://jsonapi.org).
All requests should set the JSON:API Content Type.
Content-Type: application/vnd.api+json
There may also be a benefit in using JSON:API tooling to automatically navigate and parse the JSON responses.
A typical Single Resource response looks like this:
{
"data": {
// ids are uuids represented as strings
"id": "c55edcaa-f27f-4a2e-bde9-37a70f939665",
// this typically matches the resource path - eg. /api/v1/moves/{id}
"type": "moves"
// the attributes are listed here
"attributes": {
// note this "type" is an attribute of the Move
// and does not conflict with the above "type" that states it is a "move"
"type": "prison_to_court",
// for simplicity attributes may be included in the response
// and nested many levels deep
"person": {
"id": "5da78c83-4882-4704-a015-78d350d4618b",
"details": {
"surname": "Ting",
"forenames": "Tess T"
}
}
}
}
}When multiple Resources are returned, they will be sent as an array inside the data field.
The structure of each Resource is the same as for a Single Resource.
{
"data": [
// each resource specified its type, id, and attributes
{
"type": "organisations",
"id": "example-supplier",
"attributes": {
"label": "Example Supplier",
"description": "Example Supplier PLC - Justice Division"
}
},
{
"type": "organisations",
"id": "moj",
"attributes": {
"label": "MOJ",
"description": "Ministry of Justice and associated bodies"
}
}
]
}to be completed From Version 2 of the API onwards, versioning is accomplished using part of the header: The previous V1 path-style versioning will be (may already be) deprecated.
to be completed from assurance doc
In order to supply a stable, secure, safe, and reliable service, Suppliers systems will need to be resilient to system outages, and in extreme cases to failover to paper based processes.
Moving is event based and asynchronous.
We must assume that Events can be received out of order and with variable latency (from milliseconds in the best case, to multiple days when things go wrong).
The flow for this is as follows:-