HMPPS Integration 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. It's 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.
• 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
• HMPPS Auth

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 and linting code.

./gradlew addKtlintFormatGitPreCommitHook addKtlintCheckGitPreCommitHook

Usage

Running the application locally

To run the application using IntelliJ:

1. Start dependencies using make serve-dependencies
2. Select the HmppsIntegrationApi run configuration file.
3. Click 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.

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

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,

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. A client can have different permissions i.e. read, write, reporting, although strangely the column name is called ​​autoapprove.

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.

2. 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 all tests using the command line:

make test

To run unit tests using the command line:

make unit-test

To run smoke tests using the command line:

make smoke-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

• Creating an environment
• Setting up a CircleCI context for deployment
• Setting up a new consumer
• Updating diagrams
• Useful commands

Related repositories

Name	Purpose
HMPPS Integration API Documentation	Provides documentation for API consumers.

License

MIT License