Community API
Spring Boot Java 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.test.probation.service.justice.gov.uk/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.
Running locally
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.
If running the application in intellij then you will need
--add-opens java.naming/com.sun.jndi.ldap=ALL-UNNAMED
in the jvm configuration, otherwise the LDAP configuration will not work.
Testing locally
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.
Obtaining a token
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
Using the 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.
Gradle commands
Build and run tests
./gradlew build
Assemble the app
./gradlew assemble
This makes the JAR executable by including a manifest.
Start the application default profile
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
Start the application for secure endpoints
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
Start the application with Delius Oracle db
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
Start the application with real LDAP
SPRING_LDAP_URLS=ldap://<ldap_addr>:<ldap_port> SPRING_LDAP_USERNAME=cn=orcladmin SPRING_LDAP_PASSWORD=<secret> java -jar build/libs/community-api.jar
Start the app with the DEV profile. In this mode the H2 database contains a small data set
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:
Additional configuration
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
Default port
Starts the application on port '8080'. To override, set server.port (eg SERVER_PORT=8099 java -jar etc etc)
Unit / Integration Tests
Unit Tests
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
.
Integration Tests
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
.
Test sets plugin
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.
Running tests in CI
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.
Documentation
http://localhost:8080/api/swagger-ui.html
Endpoints curl examples
Logon
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'
Get offender details
curl -X GET http://localhost:8080/api/offenders/12344568 -H 'Authorization: bearer <token>'
Application info
curl -X GET http://localhost:8080/api/info
Application health
curl -X GET http://localhost:8080/api/health
Application Ping
curl -X GET http://localhost:8080/api/health/ping
Health
api/health/ping
: provides a simple statusUP
return. This should be used by dependent systems to check connectivity to whereabouts, rather than calling theapi/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.
Alerts
Inactivity alert
There is an alert in Application Insights called Community API - Inactivity alert
. It fires if community-api hasn't received any successful requests in the last 10 minutes.
If the alert fires then look for any recent releases of community-api that may have introduced a problem. If not then ask in the MOJ Slack channel hmpps-community-pr
for assistance. Note that the alert occasionally fires overnight during quiet periods - these can be ignored.