This is the Villain REST API microservice. It is a classical HTTP microservice exposing CRUD operations on Villains. Villain information is stored in a PostgreSQL database. This service is implemented using RESTEasy Reactive with blocking endpoints and Quarkus Hibernate ORM with Panache's active record pattern.
Additionally, this application favors field injection of beans (i.e. @Inject
annotation) over constructor injection.
The following table lists the available REST endpoints. The OpenAPI document for the REST endpoints is also available.
Path | HTTP method | Query Param(s) | Response Status | Response Object | Description |
---|---|---|---|---|---|
/api/villains |
GET |
name_filter |
200 |
List<Villain> |
All Villains. Empty array ([] ) if none. Optional name_filter query parameter for filtering results by name (case-insensitive). |
/api/villains |
POST |
201 |
New Villain created. Location header contains URL to retrieve Villain |
||
/api/villains |
POST |
400 |
Invalid Villain passed in request body (or no request body found) | ||
/api/villains |
DELETE |
204 |
Deletes all Villains | ||
/api/villains |
PUT |
201 |
Replaces all villains with the passed-in villains. Location header contains URL to retrieve all Villains |
||
/api/villains |
PUT |
400 |
Invalid Villain s passed in request body (or no request body found) |
||
/api/villains/random |
GET |
200 |
Villain |
Random Villain | |
/api/villains/random |
GET |
404 |
No Villain found | ||
/api/villains/{id} |
GET |
200 |
Villain |
Villain with id == {id} |
|
/api/villains/{id} |
GET |
404 |
No Villain with id == {id} found |
||
/api/villains/{id} |
PUT |
204 |
Completely replaces a Villain | ||
/api/villains/{id} |
PUT |
400 |
Invalid Villain passed in request body (or no request body found) | ||
/api/villains/{id} |
PUT |
404 |
No Villain with id == {id} found |
||
/api/villains/{id} |
PATCH |
200 |
Villain |
Partially updates a Villain. Returns the complete Villain. | |
/api/villains/{id} |
PATCH |
400 |
Invalid Villain passed in request body (or no request body found) | ||
/api/villains/{id} |
PATCH |
404 |
No Villain with id == {id} found |
||
/api/villains/{id} |
DELETE |
204 |
Deletes Villain with id == {id} |
||
/api/villains/hello |
GET |
200 |
String |
Ping "hello" endpoint |
The application runs on port 8084
(defined by quarkus.http.port
in application.properties
).
From the quarkus-super-heroes/rest-villains
directory, simply run ./mvnw quarkus:dev
to run Quarkus Dev Mode, or running quarkus dev
using the Quarkus CLI. The application will be exposed at http://localhost:8084 and the Quarkus Dev UI will be exposed at http://localhost:8084/q/dev.
The application also contains a simple UI, showing the list of Villains currently stored. This UI is available at the root path (http://localhost:8084). The UI is built using the Quarkus Qute templating engine.
NOTE: Running the application outside of Quarkus dev mode requires standing up a PostgreSQL instance and binding it to the app. By default, the application is configured with the following:
Description | Environment Variable | Java Property | Value |
---|---|---|---|
Database URL | QUARKUS_DATASOURCE_JDBC_URL |
quarkus.datasource.jdbc.url |
jdbc:postgresql://localhost:5432/villains_database |
Database username | QUARKUS_DATASOURCE_USERNAME |
quarkus.datasource.username |
superbad |
Database password | QUARKUS_DATASOURCE_PASSWORD |
quarkus.datasource.password |
superbad |
Pre-built images for this application can be found at quay.io/quarkus-super-heroes/rest-villains
.
Pick one of the 4 versions of the application from the table below and execute the appropriate docker compose command from the quarkus-super-heroes/rest-villains
directory.
NOTE: You may see errors as the applications start up. This may happen if an application completes startup before one if its required services (i.e. database, kafka, etc). This is fine. Once everything completes startup things will work fine.
Description | Image Tag | Docker Compose Run Command |
---|---|---|
JVM Java 11 | java11-latest |
docker compose -f deploy/docker-compose/java11.yml up --remove-orphans |
JVM Java 17 | java17-latest |
docker compose -f deploy/docker-compose/java17.yml up --remove-orphans |
Native compiled with Java 11 | native-java11-latest |
docker compose -f deploy/docker-compose/native-java11.yml up --remove-orphans |
Native compiled with Java 17 | native-java17-latest |
docker compose -f deploy/docker-compose/native-java17.yml up --remove-orphans |
These Docker Compose files are meant for standing up this application and the required database only. If you want to stand up the entire system, follow these instructions.
Once started the application will be exposed at http://localhost:8084
.
The application can be deployed to Kubernetes using pre-built images or by deploying directly via the Quarkus Kubernetes Extension. Each of these is discussed below.
Pre-built images for this application can be found at quay.io/quarkus-super-heroes/rest-villains
.
Deployment descriptors for these images are provided in the deploy/k8s
directory. There are versions for OpenShift, Minikube, Kubernetes, and KNative.
Pick one of the 4 versions of the application from the table below and deploy the appropriate descriptor from the deploy/k8s
directory.
Description | Image Tag | OpenShift Descriptor | Minikube Descriptor | Kubernetes Descriptor | KNative Descriptor |
---|---|---|---|---|---|
JVM Java 11 | java11-latest |
java11-openshift.yml |
java11-minikube.yml |
java11-kubernetes.yml |
java11-knative.yml |
JVM Java 17 | java17-latest |
java17-openshift.yml |
java17-minikube.yml |
java17-kubernetes.yml |
java17-knative.yml |
Native compiled with Java 11 | native-java11-latest |
native-java11-openshift.yml |
native-java11-minikube.yml |
native-java11-kubernetes.yml |
native-java11-knative.yml |
Native compiled with Java 17 | native-java17-latest |
native-java17-openshift.yml |
native-java17-minikube.yml |
native-java17-kubernetes.yml |
native-java17-knative.yml |
The application is exposed outside of the cluster on port 80
.
These are only the descriptors for this application and the required database only. If you want to deploy the entire system, follow these instructions.
Following the deployment section of the Quarkus Kubernetes Extension Guide (or the deployment section of the Quarkus OpenShift Extension Guide if deploying to OpenShift), you can run one of the following commands to deploy the application and any of its dependencies (see Kubernetes (and variants) resource generation of the automation strategy document) to your preferred Kubernetes distribution.
NOTE: For non-OpenShift or minikube Kubernetes variants, you will most likely need to push the image to a container registry by adding the
-Dquarkus.container-image.push=true
flag, as well as setting thequarkus.container-image.registry
,quarkus.container-image.group
, and/or thequarkus.container-image.name
properties to different values.
Target Platform | Java Version | Command |
---|---|---|
Kubernetes | 11 | ./mvnw clean package -Dquarkus.profile=kubernetes -Dquarkus.kubernetes.deploy=true -DskipTests |
Kubernetes | 17 | ./mvnw clean package -Dquarkus.profile=kubernetes-17 -Dquarkus.kubernetes.deploy=true -DskipTests |
OpenShift | 11 | ./mvnw clean package -Dquarkus.profile=openshift -Dquarkus.kubernetes.deploy=true -DskipTests |
OpenShift | 17 | ./mvnw clean package -Dquarkus.profile=openshift-17 -Dquarkus.kubernetes.deploy=true -DskipTests |
Minikube | 11 | ./mvnw clean package -Dquarkus.profile=minikube -Dquarkus.kubernetes.deploy=true -DskipTests |
Minikube | 17 | ./mvnw clean package -Dquarkus.profile=minikube-17 -Dquarkus.kubernetes.deploy=true -DskipTests |
KNative | 11 | ./mvnw clean package -Dquarkus.profile=knative -Dquarkus.kubernetes.deploy=true -DskipTests |
KNative | 17 | ./mvnw clean package -Dquarkus.profile=knative-17 -Dquarkus.kubernetes.deploy=true -DskipTests |
KNative (on OpenShift) | 11 | ./mvnw clean package -Dquarkus.profile=knative-openshift -Dquarkus.kubernetes.deploy=true -DskipTests |
KNative (on OpenShift) | 17 | ./mvnw clean package -Dquarkus.profile=knative-openshift-17 -Dquarkus.kubernetes.deploy=true -DskipTests |
You may need to adjust other configuration options as well (see Quarkus Kubernetes Extension configuration options and Quarkus OpenShift Extension configuration options).
The
do_build
function in thegenerate-k8s-resources.sh
script uses these extensions to generate the manifests in thedeploy/k8s
directory.