aurenworks-api

This project uses Quarkus, the Supersonic Subatomic Java Framework.

If you want to learn more about Quarkus, please visit its website: https://quarkus.io/.

You can run your application in dev mode that enables live coding using:

./mvnw quarkus:dev

NOTE: Quarkus now ships with a Dev UI, which is available in dev mode only at http://localhost:8080/q/dev/.

The application can be packaged using:

./mvnw package

It produces the quarkus-run.jar file in the target/quarkus-app/ directory. Be aware that it’s not an über-jar as the dependencies are copied into the target/quarkus-app/lib/ directory.

The application is now runnable using java -jar target/quarkus-app/quarkus-run.jar.

If you want to build an über-jar, execute the following command:

./mvnw package -Dquarkus.package.jar.type=uber-jar

The application, packaged as an über-jar, is now runnable using java -jar target/*-runner.jar.

The API supports Cross-Origin Resource Sharing (CORS) for browser-based clients like the AurenWorks Studio. CORS is configured per environment profile to ensure security compliance.

CORS is disabled by default and only enabled in profiles where origins are explicitly defined. This follows the security rule: "only enable CORS for defined origins."

CORS is automatically configured for development with the studio development server:

• Allowed Origin: http://localhost:5173
• Configuration: src/main/resources/application-dev.properties

When running in dev mode (./mvnw quarkus:dev), CORS is automatically enabled for the development studio.

CORS must be explicitly configured for production deployments. The production profile (application-prod.properties) has CORS disabled by default until the production studio domain is configured.

To enable CORS in production:

1. Edit src/main/resources/application-prod.properties
2. Uncomment and configure the production studio domain:

# Production Profile Configuration
# CORS: Allow studio production domain
quarkus.http.cors.enabled=true
quarkus.http.cors.origins=https://studio.aurenworks.com

Important Security Notes:

• Only specify the exact production studio domain(s) - do not use wildcards
• Use HTTPS for production origins
• Multiple origins can be specified as a comma-separated list
• CORS will remain disabled if quarkus.http.cors.enabled=true is not set, even if origins are defined

The following are configured globally (when CORS is enabled):

• Allowed Headers: Authorization, Content-Type, Accept, Origin, X-Requested-With
• Allowed Methods: GET, POST, PUT, DELETE, OPTIONS, PATCH
• Credentials: Enabled (required for authentication headers)

Integration tests verify CORS functionality. Run the CORS tests with:

./mvnw test -Dtest=CorsResourceTest

You can create a native executable using:

./mvnw package -Dnative

Or, if you don't have GraalVM installed, you can run the native executable build in a container using:

./mvnw package -Dnative -Dquarkus.native.container-build=true

You can then execute your native executable with: ./target/aurenworks-api-1.0.0-SNAPSHOT-runner

If you want to learn more about building native executables, please consult https://quarkus.io/guides/maven-tooling.

This project uses Spotless for code formatting and style enforcement. Spotless is configured to use the Eclipse formatter with 2-space indentation as specified in the project rules.

To check if your code is properly formatted:

./mvnw spotless:check

To automatically format your code:

./mvnw spotless:apply

• Java files: Formatted using Eclipse formatter with eclipse-formatter.xml
• XML files: Formatted using Eclipse WTP XML formatter
• Import management: Unused imports are automatically removed
• Annotations: Properly formatted
• Line endings: UNIX style (LF)
• Encoding: UTF-8

To automatically format code before commits, you can set up a pre-commit hook:

# Create the pre-commit hook
echo '#!/bin/sh
./mvnw spotless:apply
git add .
' > .git/hooks/pre-commit
# Make it executable
chmod +x .git/hooks/pre-commit

Spotless is configured to run during the apply phase of the Maven build, ensuring all code is properly formatted before compilation.

Easily start your REST Web Services

Related guide section...