Skip to content

Version 2

Jump to bottom
Martin Ballhatchet edited this page Jul 24, 2020 · 1 revision

Book a Secure Move API v2 What’s changed?

Person / Profile

We have made changes ‘under the bonnet’ to separate a ​profile​ (usually created for each move) and a ​person​ (persistent personal details across moves). From the client’s perspective, the main change to ​person​ is that it no longer has ​assessment_answers​ - this is now held on ​profile​. The other fields such as ​first_names​, ​date_of_birth,​ etc. remain on person​.

For V2, if ​assessment_answers​ are changed, it will not affect previous ​moves​ with a different profile​.

Changing a ​person’s details, such as ​first_names​, will affect all ​moves​, past and future, for that ​person.​

A ​person​ can have many ​profiles​.

Person Identifiers

There is a breaking change in how a person’s identifiers are serialized in the v2 people endpoint.

In version 1, identifiers are returned as an array in this form:

{
"data": [
  {
    "id": "747f3914-620a-441a-847f-472c79def26c",
    "type": "people",
    "attributes": {
      "first_names": "DOMSANIGH",
      ...
    //Identifiers are a set of value attributes inside an array
    "identifiers": [
      {
        "value": "14/120018R",
        "identifier_type": "police_national_computer"
      },
      {
        "value": "G8133UA",
        "identifier_type": "prison_number"
      },
      {
        "value": "351774/14D",
        "identifier_type": "criminal_records_office"
      }
    ],
    ...
    },
    "relationships":  ...

Whereas, in version2, identifiers are returned as named attributes:

{
"data": [
  {
    "id": "747f3914-620a-441a-847f-472c79def26c",
    "type": "people",
    "attributes": {
      "first_names": "DOMSANIGH",
      //Identifiers are specific attributes of a person
      "prison_number": "G8133UA",
      "criminal_records_office": "351774/14D",
      "police_national_computer": "14/120018R",
      ...
    },
    "relationships": ...

Move

The ​move​ is now related to a ​profile​ rather than a p​erson​. This has ​assessment_answers,​ but not the personal details. To get the person’s details for the ​move​ you can request for profile.person​ to be included in the ​move​ response in the standard JSON API way.

We’ve dropped support for creating a ​move​ with a ​person;​ you now create it with a ​profile. To create the ​profile​ you must have already created a ​person​. As for V1, you can create a person​ via one of two methods, either POST to /api/people or GET /api/people, filtering on either ​police_national_computer​ or ​prison_number.​ This is described in more detail below.

A ​move​ can have 0 or 1 ​profiles​.

A ​person​ can have many moves, mediated by ​profiles​.

Documents

Documents​ are no longer associated with a ​move.​ Instead they are now associated with the profile a​ttached to the move. We have migrated ​documents​ that previously belonged to the move​ to now belong to the ​profile​. For V2, the client should associate ​documents​ with profiles​ by PATCHing the ​profile’s​ relationships.

  1. Example ​move​ payload (simplified) The payload below shows a ​move​ and an included ​profile​. The ​person​ relationship is seen on ​profile​ and can also be included in the ​move​ request.
{
  "data": {
    "id": "f0a91e16-1b0e-4elf-93fe-319dda9933e6",
    "type": "moves",
    "attributes": {
      "reference": "TM7B3A2S",
      "status": "proposed",
      "move_type": "court_appearance",
      "..."
    },
    "relationships": {
      "profile": {
        "data": {
          "type": "profiles",
          "id": "ea5ace8e-e9ad-4ca3-9977-9bf69e3b6154"
        }
      },
      "included": [
        {
          "id": "88089bbd-8719-4192-b309-f9db9105d3e1",
          "type": "profiles",
          "attributes": {
            "assessment_answers": [
              {
                "created_at": "2019-05-06",
                "expires_at": "2019-06-06",
                "title": "Asthmatic",
                "comments": "Needs an inhaler",
                "assessment_question_id": "49fa8lee-3301-4d69-f200-69e482ce1ed8",
                "category": "risk",
                "..."
              }
            ]
          },
          "relationships": {
            "person": {
              "data": {
                "type": "people",
                "id": "ea5ace8e-e9ad-4ca3-9977-9bf69e3b6154"
              }
            },
            "documents": {
              "data": [
                {
                  "type": "documents",
                  "id": "3561f372-9f1c-4e13-997e-blle1647ccel"
                }
              ]
            }
          }
        },
        "..."
      ]
    }
  }
}

Versioning

For now, you can continue to use the API as you currently do and you will continue to interact with the V1 API. However, version 1 will shortly be deprecated and we will completely remove support for version 1 in July. Exact timescales still need to be agreed.

From V2, the client must provide an ​Accept​ header which includes the version of the API in it. The only valid current options are version=1 or version=2:

Accept: application/vnd.api+json; ​version​=2

Support for the version in the path has been dropped from V2 onwards (for example, we no longer support /api/v1/people when specifying version 2 in the Accept header).

Once we remove support for version 1 it will be mandatory to pass the version in the Accept header and to make all requests without the version in the URL.

Includes

In V1, some resources (e.g. move, allocation) included some sub-resources (e.g. location, person, gender, ethnicity) in the response by default. For V2 we are adhering more closely to the JSON API spec and will no longer include any sub-resources by default. This now needs to be specified in the usual way using the include query string parameter.

Swagger Documentation

Because we have now versioned our API documentation on Swagger, the documentation itself now defaults to V2 (although the API still defaults to V1). You can change the documentation to be V1 docs by choosing V1 in the “Select a spec” dropdown on the Swagger page. For example, you can find v1 Docs here:
https://hmpps-book-secure-move-api-staging.apps.live-1.cloud-platform.service.justice.gov.uk/api-docs/index.html?urls.primaryName=PECS4%20API%20V1%20Docs

and the v2 Docs here:
https://hmpps-book-secure-move-api-staging.apps.live-1.cloud-platform.service.justice.gov.uk/api-docs/index.html?urls.primaryName=PECS4%20API%20V2%20Docs

Create ​move​ process overview

In order to create a ​move​, you must perform the following API calls in Book A Secure Move’s backend:

  1. Create a new ​person​ (a)​ or retrieve an existing one ​(b) a. POST /api/people
    To create a ​person​ with the supplied attributes
    b. GET /api/people?filter[prison_number]=:prison_number
    To get an existing person using an identifier. If the person is not yet present in the system, it will be retrieved from NOMIS and the person created for you. This will return a person with an id that can be used in step 2 below.

  2. Create a ​profile

    POST /api/people/:person_id/profiles
{
  "type": "profiles",
  "attributes": {
    "assessment_answers": [ {
      "created_at": "2019-05-06",
      "expires_at": "2019-06-06",
      "title": "Asthmatic",
      "comments":
      "Needs an inhaler",
      ...
    } ]
  }
}

    This call will create and return a profile for the person :person_id. The profile’s id will be in the response.

  3. Create a ​move​ (supplying the profile_id in the relationships either at POST time or later via a PATCH)

    POST /api/moves
{
  "type": "moves",
  "attributes": {
    "status": "proposed",
    ...
    },
  "relationships": {
    "profile": {
      "data": {
        "type": "profiles",
        "id": "ea5ace8e-e9ad-4ca3-9977-9bf69e3b6154"
      }
    }
  ...
  }
}...

    This call returns a ​move_id​ as currently.

Clone this wiki locally