-
Notifications
You must be signed in to change notification settings - Fork 1
API Guide
Status: Work In Progress
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 intended start and end location, regardless of intermediate stops.
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
** to be completed
** not sure if needed - check after diagram present
(to include: documents)
There are two elements of the API that have security requirements - the Book a Secure Move API itself, and (optionally) the 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.
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.
The flow for this is as follows:-
- API Guide
- Version 2
- Asked Questions
- Webhook & Email notifications
- Walkthroughs
- Deployment
- Useful Queries
- Data quality improvements
-
Journeys and Payment Related Calls
- Single journey move
- Redirection before move commences
- Redirection after move commences
- Lockouts and Lodgings
- Assessments
- Event Documentation
- GPS Track a move