Skip to content

Latest commit

 

History

History
143 lines (102 loc) · 20.4 KB

README.md

File metadata and controls

143 lines (102 loc) · 20.4 KB
Raw

Superheroes Villain Microservice

Table of Contents

Quality Gate Status Reliability Rating Maintainability Rating Security Rating Coverage Lines of Code

Introduction

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.

rest-villains

Exposed Endpoints

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 Villains 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

Contract testing with Pact

Pact is a code-first tool for testing HTTP and message integrations using contract tests. Contract tests assert that inter-application messages conform to a shared understanding that is documented in a contract. Without contract testing, the only way to ensure that applications will work correctly together is by using expensive and brittle integration tests.

Eric Deandrea and Holly Cummins recently spoke about contract testing with Pact and used the Quarkus Superheroes for their demos. Watch the replay and view the slides if you'd like to learn more about contract testing.

The rest-villains application is a Pact Provider, and as such, should run provider verification tests against contracts produced by consumers.

As this README states, contracts generally should be hosted in a Pact Broker and then automatically discovered in the provider verification tests.

Therefore, the Pact contract is committed into this application's source tree inside the src/test/resources/pacts directory. In a realistic scenario, if a broker wasn't used, the consumer's CI/CD would commit the contracts into this repository's source control.

The Pact tests use the Quarkus Pact extension. This extension is recommended to give the best user experience and ensure compatibility.

End-to-End UI testing with Playwright

The application UI is tested using Playwright. We are using the Quarkus Playwright extension for this.

During tests, the UI is loaded in a headless browser and interactions are tested during unit and integration tests. See UIResourceTests and UIResourceIT for details.

Benchmarking with Hyperfoil

There are some Hyperfoil benchmarks in this directory. See the README for more details.

Running the Application

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.

villains-ui

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

Running Locally via Docker Compose

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 21 java21-latest docker compose -f deploy/docker-compose/java21.yml up --remove-orphans
Native native-latest docker compose -f deploy/docker-compose/native.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.

Deploying to Kubernetes

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.

Using pre-built images

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.

Note

The Knative variant can be used on any Knative installation that runs on top of Kubernetes or OpenShift. For OpenShift, you need OpenShift Serverless installed from the OpenShift operator catalog. Using Knative has the benefit that services are scaled down to zero replicas when they are not used.

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 21 java21-latest java21-openshift.yml java21-minikube.yml java21-kubernetes.yml java21-knative.yml
Native native-latest native-openshift.yml native-minikube.yml native-kubernetes.yml native-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.

Deploying directly via Kubernetes Extensions

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 the quarkus.container-image.registry, quarkus.container-image.group, and/or the quarkus.container-image.name properties to different values.

Target Platform Java Version Command
Kubernetes 21 ./mvnw clean package -Dquarkus.profile=kubernetes -Dquarkus.kubernetes.deploy=true -DskipTests
OpenShift 21 ./mvnw clean package -Dquarkus.profile=openshift -Dquarkus.container-image.registry=image-registry.openshift-image-registry.svc:5000 -Dquarkus.container-image.group=$(oc project -q) -Dquarkus.kubernetes.deploy=true -DskipTests
Minikube 21 ./mvnw clean package -Dquarkus.profile=minikube -Dquarkus.kubernetes.deploy=true -DskipTests
Knative 21 ./mvnw clean package -Dquarkus.profile=knative -Dquarkus.kubernetes.deploy=true -DskipTests
Knative (on OpenShift) 21 ./mvnw clean package -Dquarkus.profile=knative-openshift -Dquarkus.container-image.registry=image-registry.openshift-image-registry.svc:5000 -Dquarkus.container-image.group=$(oc project -q) -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).

Tip

The do_build function in the generate-k8s-resources.sh script uses these extensions to generate the manifests in the deploy/k8s directory.