A sample Spring Boot app that exposes a REST endpoint and shows how to test it.
MIT License
A Spring Boot sample app that exposes a REST API.
It could be used as boilerplate for developing secure REST enabled microservices.
There are 2 REST endpoints:
/api/token
- An Authentication endpoint for authenticating with credentials and obtaining a/api/v1/config/markets
- A business service endpoint that allows you to manage fakeThe app has role based access control (RBAC): Users can view Market config, but only administrators can update it.
The endpoints are accessed from the http://localhost:8080
base URL.
Take a look at the Swagger docs at: http://localhost:8080/swagger-ui.html once you've configured and started the app.
You'll need JDK 11 installed on your dev box.
You can use Gradle or Maven to build the app.
Both Gradle Wrapper and Maven Wrapper are included in the project.
./gradlew build
./gradlew javadoc
and look in the ./build/docs/javadoc
folder../mvnw clean install
./target/apidocs
folders after the build completes.The app uses the Google Style Guide which is enforced during both the Gradle and Maven build - see the build.gradle and pom.xml files respectively. The Checkstyle report locations are:
./build/reports/checkstyle/main.html
./target/checkstyle-result.xml
Code coverage is provided by JaCoCo and is enforced at build time. It's currently set to 80% line coverage. See the build files. The coverage report locations are:
./build/report/jacoco/test/html/index.html
./target/jacoco-report/index.html
SpotBugs is run at build time. Any bugs found will fail the build. The bug report locations are:
./build/report/jacoco/test/html/index.html
./target/spotbugsXml.xml
Unit tests are run as part of both Gradle and Maven builds.
The endpoints are tested using Spring Boot Test utils.
The test report locations are:
build/reports/tests/test/index.html
./target/surefire-reports
You must change the restapi.jwt.secret
value in the
./config/application.properties before using the REST API over a public network.
This is the key that is used to sign your web tokens - the JWTs are signed using the HS512 algorithm.
Other interesting configuration includes:
restapi.jwt.expiration
- the expires time of the JWT. Set to 10 mins. Be sure you know therestapi.jwt.issuer
- the issuer of the JWT.restapi.jwt.audience
- the audience the JWT is meant for - your client.restapi.jwt.allowed_clock_skew
- to allow for time differences between the server and the client.server.port
- the port the app will listen on for incoming requests.You must change the PASSWORD
values in the
./src/main/resources/import.sql
before using the REST API over a public network - see instructions in the file on how to
bcrypt your passwords.
2 users have been set up out of the box: user
and admin
. These users have user
and admin
roles respectively. Passwords are the same as the usernames - remember to change these :-)
When the app starts up, Spring Boot will load the import.sql
file and store the users and their
access rights in its H2 in-memory database.
From the project root folder: ./app.sh [start|stop|status]
The app.sh script is configured to work with Gradle builds by default - it looks for
the app jar in the ./build/libs
folder. For Maven builds, change the lib_dir
variable to point
to the ./target
folder.
You can also run the app using Gradle or Maven:
./gradlew bootRun
./mvnw spring-boot:run
Check out the Swagger docs once the app is up and running: http://localhost:8080/swagger-ui.html
The REST API endpoints require a valid JWT to be passed in the Authorization
header of any requests.
To obtain a JWT, your REST client needs to call the /api/token
endpoint with a valid username/password
contained in the import.sql
file. See the
Authentication
Swagger docs for how to do this.
The returned JWT expires after 10 mins. Your client should call the /api/refresh
endpoint with the
JWT before it expires in order to get a new one. Alternatively, you can re-authenticate using the
/api/token
endpoint.
Out of the box, the app listens on port 8080
for plain HTTP connections.
This is fine for playing with the app, but the REST API must be configured to use TLS before accessing it over a public network.
You will need to create a keystore - the command to create a PKCS12 self-signed certificate is shown below:
keytool -genkeypair -alias rest-api-keystore -keyalg RSA -keysize 2048 -storetype PKCS12 -keystore keystore.p12 -validity 3650
The keystore must be on the app's classpath - you can put it in the ./src/main/resources and re-build the app to get up and running fast. For a Production system, you'll want to replace the self-signed certificate with a CA signed certificate.
The 'TLS Configuration' section in the ./config/application.properties file needs the following properties set:
# Spring Boot profile for REST API.
# Must use https profile in Production environment.
spring.profiles.active=https
# SSL (TLS) configuration to secure the REST API.
# Must be enabled in Production environment.
server.port=8443
security.require-ssl=true
server.ssl.key-store=classpath:keystore.p12
server.ssl.key-store-password=secret
server.ssl.key-store-type=PKCS12
Logging for the app is provided by log4j.
The log file is written to logs/app.log
using a rolling policy. When a log file size reaches
100 MB or a new day is started, it is archived and a new log file is created.
The app will create up to 7 archives on the same day; these are stored in a directory based on the current year and month. Only the last 90 archives are kept. Each archive is compressed using gzip.
The logging level is set at info
. You can change this default logging configuration in
the config/log4j2.xml
file.
Issues and new features are managed using the project Issue Tracker - submit bugs here.
You are welcome to take on new features or fix bugs! See here for how to get involved.