API Maintenance Mode with Spring Boot

This project illustrates how to easily manage a maintenance mode on Spring boot based APIs

Requirements

This demo has been developed with the following piece of software:

• OpenJDK 11.0.10
• Spring Boot 2.5.0
• Maven 3.8.1

How to run it

Build your application using this command:

mvn clean install

Then, run this command

java -jar ./target/maintenance-mode-0.0.1-SNAPSHOT.jar

Check that is ready:

curl -s http://localhost:8080/actuator/health/readiness 

We can see 2 live probes:

• one relative to the database connection automatically provided by Spring
• an other one related to an application specific maintenance flag.

By default the maintenance flag is set to false. That means that the service is ready.

There is an endpoint enabling to read and set that flag.

Let's put the service in maintenance:

curl -X 'PUT' \
  'http://localhost:8080/api/maintenance' \
  -w "\n" \
  -H 'Content-Type: text/plain' \
  -d 'true' -v

We get an HTTP 204 answer (no-content).

We can check now that our API is no longer ready:

curl -s http://localhost:8080/q/health/ready

Let's inspect the code of MaintenanceController.retreiveInMaintenance() to see how the HealthCheck probe is developed.

Let's try to read a random url:

curl -s \
  -w "\n" \
  'localhost:8080/api/random' 

We get an answer from our API:

{
  "reason": "Service currently in maintenance"
}

Let's browse the code of CheckMaintenanceFilter.java and see how this answer is provided using a good old servlet filter.

curl -X 'PUT' \
  'http://localhost:8080/api/maintenance' \
  -w "\n" \
  -H 'Content-Type: text/plain' \
  -d 'false' -v

We can now check now that our API is ready again:

curl -s http://localhost:8080/actuator/health/readiness