HMPPS External API

Contents

• About this project
  • External dependencies
  • Data Analysis Tooling
• Get started
  • Using IntelliJ IDEA
• Usage
  • Running the application
    • With dependent services
  • Running the tests
  • Running the linter
  • Running all checks
  • Request logging
• Further documentation
• Developer guides
• Related repositories
• License

About this project

A long-lived API that exposes data from HMPPS systems such as the National Offender Management Information System (NOMIS), nDelius (probation system) and Offender Assessment System (OASys), providing a single point of entry for consumers.

Formerly named the "HMPPS Integration API", it was renamed to "HMPPS External API" in September 2025, though many references to the old name persist.

It is built using Spring Boot and Kotlin as well as the following technologies for its infrastructure:

• AWS - Services utilise AWS features through Cloud Platform such as Elastic Container Registry (ECR) to store our built artifacts as well as Simple Storage Service (S3). The CI/CD pipeline stores and retrieves them from there as required.
• CircleCI - Used for our build platform, responsible for executing workflows to build, validate, test and deploy our project.
• Cloud Platform - Ministry of Justice's (MOJ) cloud hosting platform built on top of AWS which offers numerous tools such as logging, monitoring and alerting for our services.
• Docker - The API is built into docker images which are deployed to our containers. A docker hub licence will be required to run all unit tests.
• Kubernetes - Creates 'pods' to host our environment. Manages auto-scaling, load balancing and networking to our application.

External dependencies

This solution is dependent on:

• Prison API
• Prisoner Search
• Probation Offender Search
• External API and nDelius
• Effective proposal framework and Delius
• HMPPS Auth
• Assess Risks and Needs (ARNS)
• Adjudications
• Case Notes
• Create and Vary License
• Incentives
• Manage POM Case
• Non-associations
• Personal Relationships
• Education and Work Plan
• Prisoner Alerts
• Manage Prison Visits
• Risk Management
• Locations Inside Prison
• Activities Management
• Health and Medication
• Support for additional needs

These things depend upon this solution:

• Consumer Applications (MAPPS)

Data Analysis Tooling

Included within this repository is Python-based functionality used by the team to enhance data researching and analysis.

You can find information on how to use this in the data_analysis section of our scripts.

Get started

Using IntelliJ IDEA

When using an IDE like IntelliJ IDEA, getting started is very simple as it will handle installing the required Java SDK and Gradle versions. The following are the steps for using IntelliJ but other IDEs will prove similar.

1. Clone the repo.

   git clone git@github.com:ministryofjustice/hmpps-integration-api.git

2. Launch IntelliJ and open the hmpps-integration-api project by navigating to the location of the repository.

   Upon opening the project, IntelliJ will begin downloading and installing necessary dependencies which may take a few minutes.

3. Enable pre-commit hooks for formatting, linting, and secret scanning.

    # Install pipx if not already installed
    brew install pipx
   
    # Ensure the path to pipx-installed tools is active
    pipx ensurepath
    # Restart your terminal after running this
   
    # Install pre-commit
    pipx install pre-commit
   
    # Install hooks into .git/hooks
    pre-commit install
   

Usage

Running the application locally

To run the application using IntelliJ:

1. Start dependencies using make serve-dependencies Note: Make sure all docker services are stopped before running this command.
2. Select the HmppsIntegrationApi run configuration file.
3. Click the run button.

Note: If IntelliJ dose not automatically detect a run configuration you will need to make one yourself. To do this go into edit a configuration, add a Gradle setup. There we want to

1. Set the Run command to be bootRun
2. Set the Gradle project to be the root of hmpps-integration-api
3. Set Environment Variables to be SPRING_PROFILES_ACTIVE=local

Example setup

After that you can now use the run button.

Or, to run the application using the command line:

SPRING_PROFILES_ACTIVE=local ./gradlew bootRun

Then visit http://localhost:8080/swagger-ui/index.html.

With dependent services

Simulators are used to run dependent services for running the application locally and in smoke tests. They use Prism which creates a mock server based on an API's latest OpenAPI specification file.

It's possible to run the application with dependent services like the NOMIS / Prison API and HMPPS Auth with Docker using docker-compose.

1. Build and start the containers for each service. Note: Make sure all docker services are stopped before running this command.

   make serve

   Each service is then accessible at:

   • http://localhost:8080 for this application
   • http://localhost:4010 to http://localhost:40XX for mocked HMPPS APIs
   • http://localhost:9090 for the HMPPS Auth service

2. To call the integration-api, you need to pass a distinguished name in the subject-distinguished-name header. The CN attribute should match the client you wish to access the service as. The list of clients and their authorised endpoints can be found in application-local-docker.yml.

   For example,
   
   ```bash
   curl -H "subject-distinguished-name: O=local,CN=all-access" http://localhost:8080/health
   ```
   
   As part of getting the HMPPS Auth service running
   locally, [the in-memory database is seeded with data including a number of clients](https://github.com/ministryofjustice/hmpps-auth/blob/main/src/main/resources/db/dev/data/auth/V900_0__clients.sql). A client can have different permissions i.e. read, write, reporting, although strangely the column name is called `​​autoapprove`.
   

3. If you wish to call an endpoint of a dependent API directly, an access token must be provided that is generated from the HMPPS Auth service. Use the following cURL to generate a token for a HMPPS Auth client.

   curl -X POST "http://localhost:9090/auth/oauth/token?grant_type=client_credentials" \
     -H 'Content-Type: application/json' \
     -H "Authorization: Basic $(echo -n "hmpps-integration-api-client:clientsecret" | base64)"

   This uses the client ID: hmpps-integration-api-client and the client secret: clientsecret. A number of seeded clients use the same client secret.

   A JWT token is returned as a result, it will look like this:

   {
     "access_token": "eyJhbGciOiJSUzI1NiIs...BAtWD653XpCzn8A",
     "token_type": "bearer",
     "expires_in": 3599,
     "scope": "read write",
     "sub": "hmpps-integration-api-client",
     "auth_source": "none",
     "jti": "Ptr-MIdUBDGDOl8_qqeIuNV9Wpc",
     "iss": "http://localhost:9090/auth/issuer"
   }

   Using the value of access_token, you can call a dependent API using it as a Bearer Token.

   There are a couple of options for doing so such as curl, Postman and using in-built Swagger UI via the browser e.g. for Prison API at http://localhost:4030/swagger-ui/index.html which documents the available API endpoints.

Running the tests

The testing framework used in this project is Kotest.

To run the tests using IntelliJ:

1. Install the Kotest IntelliJ plugin. This provides the ability to easily run a test as it provides run buttons (gutter icons) next to each test and test file.
2. Click the run button beside a test or test file.

To run unit and integration tests using the command line:

make test

To run unit tests using the command line:

make unit-test

To run integration tests using the command line:

make integration-test

Running the linter

To lint the code using Ktlint:

make lint

To autofix any styling issues with the code:

make format

Running all checks

To run all the tests and linting:

make check

Request logging

This can be done within logback-spring.xml. To enable request logging, update the value of the level property within the logger named <application>.config.RequestLogger to the desired logger level.

<logger name="uk.gov.justice.digital.hmpps.hmppsintegrationapi.config.RequestLogger" additivity="false" level="DEBUG">
    <appender-ref ref="logAppender"/>
    <appender-ref ref="consoleAppender"/>
</logger>

Note, this will only specifically enable the RequestLogger.

Further documentation

• Architecture Decision Records (ADRs)
• Architecture diagrams
• Audit
• Authentication and Authorisation
• Backups
• Banner
• Environments
• High availability
• Monitoring and Alerting
• Security
• Performance
• Runbook

Developer guides

• Certificate Renewal
• Creating an environment
• Renew mutual TLS server certificate
• Setting up a new consumer
• Setting up a CircleCI context for deployment
• Updating diagrams
• Useful commands
• Validating Upstream Responses

Related repositories

Name	Purpose
HMPPS Integration Events	Creates integration events triggered by upstream MoJ domain events. (Archived, no longer in use)
HMPPS Integration API Documentation	Previously provided documentation for API consumers. No longer in use.

License

MIT License