先生と生徒の会話形式で理解しよう

生徒

「QuarkusでREST APIを作っているんですが、URLに付けるパラメータの受け取り方がよく分かりません…」

先生

「QuarkusのREST機能では、リクエストパラメータをとても簡単に扱えます。アノテーションを使うのがポイントですよ。」

生徒

「GETリクエストの?name=xxxみたいなやつですよね？」

先生

「その通りです。では、Quarkus REST APIでの基本から順番に見ていきましょう。」

1. Quarkus REST APIとリクエストパラメータの基本

QuarkusはJava向けの軽量フレームワークで、REST APIの開発がとてもシンプルに行えることが特徴です。 Webアプリケーションやバックエンド開発では、クライアントから値を受け取る場面が頻繁にあります。その代表例がリクエストパラメータです。

リクエストパラメータとは、URLの末尾に付けてサーバーへ送信する情報のことです。例えば検索条件やページ番号、ユーザー名など、比較的簡単な値を送る用途でよく使われます。 Quarkus RESTでは、JAX-RSの仕組みを利用して直感的に受け取れます。

2. クエリパラメータの受け取り方

最もよく使われるのがクエリパラメータです。クエリパラメータは、URLの「?」以降に指定します。 Quarkusでは、アノテーションを使ってメソッドの引数として簡単に受け取れます。


import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.QueryParam;

@Path("/hello")
public class HelloResource {

    @GET
    public String hello(@QueryParam("name") String name) {
        return "こんにちは、" + name + "さん";
    }
}

この例では、URLに指定されたnameという値を受け取り、そのままレスポンスとして返しています。ブラウザでアクセスすると、動作が分かりやすく確認できます。


http://localhost:8080/hello?name=Quarkus

3. 複数のリクエストパラメータを扱う方法

実際の開発では、ひとつだけでなく複数のリクエストパラメータを扱うことがほとんどです。 Quarkus REST APIでは、引数を増やすだけで簡単に対応できます。特別な設定は不要なので、初心者でも安心です。


import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.QueryParam;

@Path("/calc")
public class CalcResource {

    @GET
    public String calc(@QueryParam("a") int a, @QueryParam("b") int b) {
        int result = a + b;
        return "計算結果は " + result + " です";
    }
}

上記のように数値も自動的に変換されます。 URLで指定した値を使って簡単な計算処理を行うことができます。


http://localhost:8080/calc?a=3&b=5

4. リクエストパラメータが存在しない場合の考え方

リクエストパラメータは必ず送られてくるとは限りません。そのため、値が指定されなかった場合の挙動も理解しておく必要があります。 Quarkusでは、指定がなければnullやデフォルト値として扱われます。


import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.QueryParam;

@Path("/greet")
public class GreetResource {

    @GET
    public String greet(@QueryParam("name") String name) {
        if (name == null) {
            return "名前が指定されていません";
        }
        return "ようこそ、" + name + "さん";
    }
}

初心者のうちは、まずはnullチェックを行う方法を覚えておくと安心です。後々、より便利な方法も学習できますが、基礎をしっかり押さえることが大切です。

5. パスパラメータとの違いを理解する

Quarkus REST APIでは、リクエストパラメータ以外にもパスパラメータがあります。これはURLの一部として値を埋め込む方法です。役割の違いを理解すると、API設計が分かりやすくなります。


import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.PathParam;

@Path("/user")
public class UserResource {

    @GET
    @Path("/{id}")
    public String getUser(@PathParam("id") int id) {
        return "ユーザーIDは " + id + " です";
    }
}

検索条件やオプションにはリクエストパラメータ、識別子にはパスパラメータという使い分けを意識すると、REST APIが整理されます。