4.8. REST エンドポイントパス解決における変更

Red Hat ビルドの Quarkus 1.11 では、アプリケーションとアプリケーション以外の REST エンドポイントのパスは、一般的な絶対ルートパスと相対的に解決されます。REST エンドポイントのデフォルトの一般的なルートパスは、以下のように設定されます。

相対ルートパスは、quarkus.http.root-path プロパティーによって定義されるルートパスの下にネストされる点に留意してください。たとえば、quarkus.http.root-path プロパティーに定義されたルートパスが / に設定され、quarkus.http.non-applicationroot-path プロパティーに定義されたアプリケーション以外のエンドポイントのルートパスが q に設定されている場合、アプリケーション以外のエンドポイントの絶対エンドポイントパスは /q/<non-application-endpoint-name> になります。

ただし、アプリケーション以外の個々のエンドポイントのパスを、/q/<non-application-endpoint-name> に配置するように明示的に設定することもできます。

エンドポイントパスは quarkus.http.root-path および quarkus.http.non-application-root-path によって設定されるルートパスに相対的と解釈されるため、アプリケーションのエンドポイントに設定するカスタムパスおよびサブパスから先頭のスラッシュ ((/) を除外する必要があります。

たとえば、アプリケーションの REST コントローラーで Prometheus のメトリクスエンドポイントを公開する場合は、エンドポイントが /q/metrics で公開されるように、@Path アノテーションのエンドポイントパスを metrics に設定する必要があります。同じパス値を /metrics に設定すると、メトリクスエンドポイントは /metrics で公開されます。

アプリケーション以外のエンドポイントを別の namespace の下に設定する例

たとえば、プロジェクトの application.properties ファイルに以下のプロパティーを設定し、/api ルートパスで hello エンドポイントアプリケーションを、そして /api/q パスで metrics エンドポイントを公開することができます。

quarkus.http.root-path=/api
quarkus.http.non-application-root-path=q

quarkus.http.root-path=/api
quarkus.http.non-application-root-path=q

この設定では、/api/hello と /api/q/metrics の両方がパブリックです。つまり、/api/hello にアクセスするパーミッションを持つユーザーは、/api/q/metrics エンドポイントにもリクエストを送信して、有効な Response を受け取ることができます。

health エンドポイントをパブリック以外にする場合は、application.properties のアプリケーション以外のエンドポイントのルートパスを /q namespace に設定できます。

quarkus.http.root-path=/api
quarkus.http.non-application-root-path=/q

quarkus.http.root-path=/api
quarkus.http.non-application-root-path=/q

この設定では、/api/hello エンドポイントはパブリックですが、/q/metrics は異なるアクセスパーミッションを設定できる別の namespace に公開されています。

Red Hat ビルドの Quarkus 1.11 では、元のアプリケーション以外のエンドポイントパスに送信されたリクエストは、/q namespace の新しいパスに自動的にリダイレクトされます。

プロジェクトの application.properties ファイルで以下の属性を設定して、アプリケーション以外のエンドポイントパスの自動リダイレクトを無効にすることができます。

quarkus.http.redirect-to-non-application-root-path=false

quarkus.http.redirect-to-non-application-root-path=false

quarkus.http.non-application-root-path の値を、絶対アプリケーションエンドポイントルートの値に解決する変数に設定し、すべてのエンドポイントの絶対エンドポイントのルートパスを使用するようにアプリケーションを切り替えることができます。

quarkus.http.non-application-root-path=${quarkus.http.root-path}

quarkus.http.non-application-root-path=${quarkus.http.root-path}