Spring Boot 2, Java 11 API for accessing Probation offenders information

The service provides REST access to the Delius Oracle DB.

Documentation including URLs for the various endpoints can be found on the test instance at https://community-api-public.test.delius.probation.hmpps.dsd.io/swagger-ui/index.html (VPN / trusted network required). We are in the process of switching to using HMPPS Auth for all the endpoints in the service, these are identified by (secure) after the name and are under /secure rather than /api. The test instance is connected to the test instance of Delius and the dev (t3) instance of Auth.

For credentials to access the test service or any questions on the service please ask at #ask-hmpps-api in slack.

The easiest way to run the application locally is using docker-compose:

docker-compose pull && docker-compose up

This will grab the latest versions of auth and community api and start both - auth on 9090 and community api on 8080.

We use Postman to test the API calls. The swagger docs can be imported as a collection to make it easier to test out a single call. If using browser based postman, you may need to copy the response from that URL and import the collection as raw text.

Calling the API is a two step process - obtaining a token from auth and then using the token in community API.

Within Postman in the Authorization tab select OAuth 2.0 type and add the authorization data to request headers. The grant type should be Client Credentials, access token URL http://localhost:9090/auth/oauth/token, client ID and secret both set to community-api-client and client authentication set to Send as Basic Auth header. Then click "Get new access token" and "Use access token".

Alternatively using curl:

curl --location --request POST "http://localhost:9090/auth/oauth/token?grant_type=client_credentials" --header "Authorization: Basic $(echo -n community-api-client:community-api-client | base64)"  | jq .access_token

In the local environment some sample data is seeded automatically. src/main/resources/db/data/V1_3__offender_X320741_data.sql contains a single offender data so in Postman making a GET request to http://localhost:8080/secure/offenders/crn/X320741/identifiers should then bring back the offender identifiers.

Alternatively using curl:

curl 'http://localhost:8080/secure/offenders/crn/X320741/identifiers' --header 'Authorization: Bearer XXX'

where XXX should be replaced by the token.

./gradlew build

./gradlew assemble

This makes the JAR executable by including a manifest.

Without additional configuration this mode uses an in memory H2 (empty) database and an in memory LDAP service which references a file resource in the JAR (schema.ldif).

java -jar build/libs/community-api.jar

When running locally and accessing the secure endpoints it is recommended to run the HMPPS Authentication server.

docker-compose up oauth

or to run the latest version of this API from the docker repository

docker-compose up

set SPRING_PROFILES_ACTIVE=oracle

SPRING_DATASOURCE_URL=jdbc:oracle:thin:@<VM Oracle IP address>:1521:DNDA SPRING_PROFILES_ACTIVE=oracle java -jar build/libs/community-api.jar

SPRING_LDAP_URLS=ldap://<ldap_addr>:<ldap_port> SPRING_LDAP_USERNAME=cn=orcladmin SPRING_LDAP_PASSWORD=<secret> java -jar build/libs/community-api.jar

SPRING_PROFILES_ACTIVE=dev ./gradlew bootRun

H2 Web console - http://localhost:8080/h2-console

JDBC URL: jdbc:h2:mem:testdb;Mode=Oracle USER: sa PASSWORD:

The application is configured with conventional Spring parameters. The Spring documentation can be found here:

https://docs.spring.io/spring-boot/docs/current/reference/html/common-application-properties.html

Starts the application on port '8080'. To override, set server.port (eg SERVER_PORT=8099 java -jar etc etc)

The unit tests can be found in the normal source set test. This contains tests do not require running the Spring Boot application or priming the database. They should be very quick to run.

The unit tests can be run with the command ./gradlew test.

The integration tests can be found in the additional source set testIntegration. This contains long running tests that generally start up the full application with local database.

The integration tests can be run with the command ./gradlew testIntegration.

Where did the new source set testIntegration come from?

The plugin org.unbroken-dome.test-sets is used to introduce a new source set called testIntegration which complements the existing source set test. Note that the plugin handles everything a source set needs, including new configurations. For example, Wiremock is now a dependency of the testIntegrationImplementation configuration as it is only needed by the integration tests.

In the CircleCI config we run the gradle command ./gradlew check which is intended to perform all validation of the project.

The check task always dependsOn the test - it now also depends on the testIntegration task.

http://localhost:8080/api/swagger-ui.html

The logon body must be a fully qualified LDAP distinguished name:

cn=nick.redshaw,cn=Users,dc=moj,dc=com

curl -X POST http://localhost:8080/api/logon -H 'Content-Type: text/plain' -d 'uid=jihn,ou=people,dc=memorynotfound,dc=com'

curl -X GET http://localhost:8080/api/offenders/12344568 -H 'Authorization: bearer <token>'

curl -X GET http://localhost:8080/api/info

curl -X GET http://localhost:8080/api/health

curl -X GET http://localhost:8080/api/health/ping

• api/health/ping: provides a simple status UP return. This should be used by dependent systems to check connectivity to whereabouts, rather than calling the api/health endpoint.
• api/health: provides information about the application health and its dependencies. This should only be used by whereabouts health monitoring (e.g. pager duty) and not other systems who wish to find out the state of whereabouts.
• api/info: provides information about the version of deployed application.