Helidon lets you easily include health, metrics, and OpenAPI services in your Helidon application. These services add endpoints to your application so that clients can retrieve information about it. As with the application endpoints you write, these endpoints represent resources that can be shared across origins.

For example, several websites related to OpenAPI run a web application in your browser. You provide the URL for your application to the browser application. The browser application uses the URL to retrieve the OpenAPI document that describes the application’s endpoints directly from your application. The browser application then displays a user interface that you use to "drive" your application. That is, you provide input, have the web application send requests to your application endpoints, and then view the responses. This scenario is exactly the situation CORS addresses: an application in the browser from one origin — the user interface downloaded from the website — requests a resource from another origin — the /openapi endpoint which Helidon’s OpenAPI built-in service automatically adds to your application.

Integrating CORS support into these built-in services allows such third-party web sites and their browser applications — or more generally, apps from any other origin — to work with your Helidon application.

Because all three of these built-in Helidon services serve only GET endpoints, by default the integrated CORS support in all three services permits any origin to share their resources using GET, HEAD, and OPTIONS HTTP requests. You can customize the CORS set-up for these built-in services independently from each other using configuration. You can use this override feature to control the CORS behavior of the built-in services even if you do not add CORS behavior to your own endpoints.

To use built-in services with CORS support and customize the CORS behavior:

1. Add the built-in service or services to your application. The health, metrics, and OpenAPI services automatically include default CORS support.

2. Add a dependency on the Helidon MP CORS artifact to your Maven pom.xml file.

   If you want the built-in services to support CORS, then you need to add the CORS dependency even if your own endpoints do not use CORS.

   The Managing Dependencies page describes how you should declare dependency management for Helidon applications. For CORS support in Helidon MP, you must include the following dependency in your project:

3. Use configuration to customize the CORS behavior as needed.

The documentation for the individual built-in services describes how to add each service to your application, including adding a Maven dependency. In your application’s configuration file, the configuration for each service appears under its own key.

The Helidon MP QuickStart example uses these services, so you can use that as a template for your own application, or use the example project itself to experiment with customizing the CORS behavior in the built-in services.

You can use configuration to control whether and how each of the built-in services works with CORS.

For the health, metrics, and OpenAPI services, your configuration can include a section for CORS.

You have full control over the CORS configuration for a built-in Helidon service. Use a basic CORS config section as described in Using Configuration with CORS in Helidon MP.

The following example restricts sharing of

• the /health resource, provided by the health built-in service, to only the origin http://there.com, and

• the /metrics resource, provided by the metrics built-in service, to only the origin http://foo.com.

...
health:
  cors:
    allow-origins: [http://there.com]
metrics:
  cors:
    allow-origins: [http://foo.com]
...

If you have edited the Helidon MP QuickStart application as described in the previous topics and saved your changes, you can build and run the application. Once you do so you can execute curl commands to demonstrate the behavior changes in the metric and health services with the addition of the CORS functionality. Note the addition of the Origin header value in the curl commands, and the Access-Control-Allow-Origin in the successful responses.

Build and Run the Application

mvn package
java -jar target/helidon-quickstart-mp.jar
...
2020.05.12 05:44:08 INFO io.helidon.microprofile.server.ServerCdiExtension Thread[main,5,main]: Server started on http://localhost:8080 (and all other host addresses) in 5280 milliseconds (since JVM startup).
...

Retrieve Metrics

curl -i -H "Origin: http://other.com" http://localhost:8080/metrics

HTTP/1.1 403 Forbidden
Date: Mon, 11 May 2020 11:08:09 -0500
transfer-encoding: chunked
connection: keep-alive

curl -i -H "Origin: http://foo.com" http://localhost:8080/metrics

HTTP/1.1 200 OK
Access-Control-Allow-Origin: http://foo.com
Content-Type: text/plain
Date: Mon, 11 May 2020 11:08:16 -0500
Vary: Origin
connection: keep-alive
content-length: 6065

# TYPE base_classloader_loadedClasses_count gauge
# HELP base_classloader_loadedClasses_count Displays the number of classes that are currently loaded in the Java virtual machine.
base_classloader_loadedClasses_count 3568
...

Retrieve Health

curl -i -H "Origin: http://foo.com" http://localhost:8080/health

HTTP/1.1 403 Forbidden
Date: Mon, 11 May 2020 12:06:55 -0500
transfer-encoding: chunked
connection: keep-alive

curl -i -H "Origin: http://there.com" http://localhost:8080/health

HTTP/1.1 200 OK
Access-Control-Allow-Origin: http://there.com
Content-Type: application/json
Date: Mon, 11 May 2020 12:07:32 -0500
Vary: Origin
connection: keep-alive
content-length: 461

{"outcome":"UP",...}