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

生徒

「QuarkusでREST APIを作れると聞いたんですが、そもそもエンドポイントって何ですか？」

先生

「エンドポイントは、ブラウザやアプリからアクセスされる“URLの受付窓口”のようなものです。Quarkusではアノテーションを使って簡単に作れます。」

生徒

「@Pathとか@GETって書いてあるのを見ましたが、意味がよく分かりません…」

先生

「大丈夫です。REST APIの基本から、Quarkusでの書き方まで順番に見ていきましょう。」

1. REST APIとエンドポイントの基本

QuarkusのREST APIを理解するために、まずREST APIの考え方を押さえます。REST APIは、URLとHTTPメソッドを使ってデータをやり取りする仕組みです。ブラウザでページを見るのも同じHTTP通信ですが、REST APIでは主にJSONなどのデータを返します。

エンドポイントとは、REST APIで用意されたURLのことです。たとえば「/hello」にアクセスすると文字列を返す、といった動きを定義します。Quarkusでは、このエンドポイントをJavaクラスとアノテーションで表現します。

初心者の方は「URLにアクセスされたときの処理を書く場所」と考えると分かりやすいです。

2. QuarkusでREST APIを作る基本構成

QuarkusのREST APIは、リソースクラスと呼ばれるJavaクラスで作ります。このクラスに@Pathを付けることで、どのURLに対応するかを決めます。

QuarkusはRESTEasyを標準で利用できるため、特別な設定をしなくてもすぐにREST API開発を始められます。これは初心者にとって大きなメリットです。

まずは、最小構成のエンドポイントを見てみましょう。


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

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

    @GET
    public String hello() {
        return "Hello Quarkus";
    }
}

このコードでは「/hello」にGETアクセスすると「Hello Quarkus」という文字列が返ります。とてもシンプルですが、REST APIの基本が詰まっています。

3. @PathでURLを指定する仕組み

@Pathは、エンドポイントのURLを指定するためのアノテーションです。クラスに付けた@Pathは共通のURLになり、メソッドに付けた@Pathはその下に続く形になります。

たとえば「/users/list」のようなURLも簡単に表現できます。URL設計はREST APIではとても重要で、Quarkusでも分かりやすい構造を作ることが推奨されます。


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

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

    @GET
    @Path("/list")
    public String list() {
        return "ユーザー一覧";
    }
}

このように@Pathを組み合わせることで、複雑なURLも整理して管理できます。

4. @GETでデータを取得する処理

@GETは、HTTPのGETメソッドに対応するアノテーションです。GETは主に「データを取得する」目的で使われます。ブラウザのアドレスバーからアクセスする場合もGETが使われます。

Quarkusでは、@GETを付けたメソッドがそのままレスポンス処理になります。戻り値をStringにすれば文字列、オブジェクトにすればJSONとして返されます。


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

@Path("/time")
public class TimeResource {

    @GET
    public String now() {
        return "現在時刻を返すAPIです";
    }
}

この例では固定文字列ですが、実際には日付やデータベースの内容を返すこともできます。

5. @POSTでデータを送信する基本

@POSTは、データを送信したり登録したりするときに使われるHTTPメソッドです。フォーム送信やJSON送信などでよく利用されます。

Quarkusでは、@POSTを付けるだけでPOSTリクエストを受け取れます。初心者の方は「登録処理用」と覚えると理解しやすいです。


import jakarta.ws.rs.POST;
import jakarta.ws.rs.Path;

@Path("/message")
public class MessageResource {

    @POST
    public String postMessage(String message) {
        return "受け取った内容: " + message;
    }
}

ここでは送信された文字列を受け取り、そのまま返しています。REST APIの動きがイメージしやすい例です。