REST APIとは？初心者向けにやさしく解説｜Springで学ぶHTTPとURL設計の基本

新人と先輩の会話形式で理解しよう

新人

「先輩、最近よく聞くREST APIって何ですか？SpringでAPIを作るときに出てきて、よく分からなくて…」

先輩

「REST APIは、Webアプリケーションでよく使われる通信の仕組みなんだ。HTTPをベースにしていて、リソースという考え方で設計されるんだよ。」

新人

「リソース…？なんだか難しそうですね。URLとの関係もよく分かりません…」

先輩

「それじゃあ、今日はRESTの基本からゆっくり説明していこう！」

1. RESTとは？HTTPとの関係

RESTとは「Representational State Transfer（表現の状態転送）」の略で、Webの基本的な仕組みを使ってデータをやり取りする設計スタイルのことを指します。Springでもよく使われる考え方で、特にREST APIという形でシステム間の通信に使われています。

RESTは、HTTPの仕組みを活用して情報をやり取りします。HTTPとは、Webブラウザとサーバーの間で情報をやり取りするための通信ルールです。たとえば、ブラウザで「https://example.com/user」と入力すると、そのURLにある情報をGETメソッドで取得する、という処理が行われています。

RESTでは、次のようなHTTPメソッドを使って操作を表現します。

GET：データの取得
POST：新しいデータの作成
PUT：既存データの更新
DELETE：データの削除

これらのHTTPメソッドを使うことで、どんな操作をしたいのかが明確に伝えられるようになります。Springでも、これらのメソッドを使ったREST APIの設計が基本になります。

2. REST APIの基本的な考え方（リソース、URL設計など）

REST APIでは、リソースという考え方がとても重要です。リソースとは、APIで操作の対象となる「情報のかたまり」のことで、たとえば「ユーザー」や「商品」などがそれにあたります。

そして、リソースにはURLを使ってアクセスします。URLはリソースの場所を表す住所のようなもので、RESTではリソースごとにきれいに整理されたURLを使います。

例えば「ユーザー情報」を操作するREST APIの場合、次のような設計になります。

ユーザー一覧の取得：/users（GET）
特定ユーザーの取得：/users/1（GET）
新規ユーザーの登録：/users（POST）
ユーザーの更新：/users/1（PUT）
ユーザーの削除：/users/1（DELETE）

URLには動詞を使わず、名詞（リソース名）で表現するのがRESTの特徴です。「/getUser」や「/createUser」などのように動詞を使うのではなく、「/users」のように対象を表すようにしましょう。

新人

「なるほど、URLでリソースを表現して、HTTPメソッドで操作の種類を分けるんですね！」

先輩

「そうだね！Springでもこのルールに沿って@Controllerを使ってREST APIを作っていくんだよ。」

では、簡単な例としてSpringの@Controllerを使って「ユーザー一覧を取得するAPI」を実装してみましょう。今回は@RestControllerは使わず、@Controllerと@ResponseBodyを組み合わせて記述します。


import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.ResponseBody;
import java.util.List;
import java.util.Arrays;

@Controller
public class UserController {

    @GetMapping("/users")
    @ResponseBody
    public List<String> getUsers() {
        return Arrays.asList("Taro", "Jiro", "Hanako");
    }
}

このコードでは、/usersにGETリクエストが送られたとき、ユーザー名の一覧を返すREST APIを作成しています。@Controllerを使いながら@ResponseBodyでレスポンスを返しているのがポイントです。

Springを使ったREST API開発では、このようなURL設計やHTTPメソッドの考え方が非常に大切です。初心者でもまずはこの基本構成から理解を始めることで、実務でも応用しやすくなります。

3. SpringでREST APIを作るには？（@Controller + @ResponseBody）

Springでは、REST APIを作成する際に@Controllerと@ResponseBodyを組み合わせることで、HTML画面ではなくレスポンスとしてJSONや文字列などを返すことができます。

@ResponseBodyを付けることで、戻り値がそのままHTTPレスポンスの本文として返されるようになります。ビュー名として解釈されずに、直接データとしてブラウザやクライアントに送信されるため、REST APIでは非常によく使われます。

通常のSpring MVCでは、@ControllerのメソッドはHTMLテンプレートを返しますが、REST APIではそれを避けて、データをそのまま返す設計になります。


import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.ResponseBody;

@Controller
public class HelloController {

    @GetMapping("/hello")
    @ResponseBody
    public String sayHello() {
        return "こんにちは、REST APIの世界へようこそ！";
    }
}

このようにすることで、「/hello」というURLにアクセスした際に「こんにちは、REST APIの世界へようこそ！」という文字列が直接HTTPレスポンスとして返されます。これはHTML画面ではなく、データそのものを返す形で、まさにREST APIの基本的なスタイルです。

4. HTTPメソッド（GET、POST、PUT、DELETE）の役割と使い方

REST APIでは、HTTPメソッドを使って「何をしたいのか」を明確に表現します。それぞれのメソッドは次のような役割を持っています。

GET：データを取得する
POST：新しいデータを追加する
PUT：既存のデータを更新する
DELETE：データを削除する

これらのメソッドをSpringで使う場合は、@GetMappingや@PostMappingなどのアノテーションを使います。それぞれのHTTPメソッドに対応するアノテーションを使い分けることで、SpringでのREST API開発がとても直感的になります。

以下に、各HTTPメソッドに対応したSpringのコード例を示します。


import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.*;

import java.util.*;

@Controller
@RequestMapping("/items")
public class ItemController {

    private List<String> itemList = new ArrayList<>(List.of("りんご", "バナナ"));

    @GetMapping
    @ResponseBody
    public List<String> getItems() {
        return itemList;
    }

    @PostMapping
    @ResponseBody
    public String addItem(@RequestParam String name) {
        itemList.add(name);
        return "追加しました：" + name;
    }

    @PutMapping
    @ResponseBody
    public String updateItem(@RequestParam int index, @RequestParam String name) {
        if (index >= 0 && index < itemList.size()) {
            itemList.set(index, name);
            return "更新しました：" + name;
        }
        return "指定されたインデックスは存在しません";
    }

    @DeleteMapping
    @ResponseBody
    public String deleteItem(@RequestParam int index) {
        if (index >= 0 && index < itemList.size()) {
            String removed = itemList.remove(index);
            return "削除しました：" + removed;
        }
        return "削除に失敗しました";
    }
}

このように、Springでは@ControllerとHTTPメソッドに対応したアノテーションを使い分けることで、リクエストの内容に応じた処理を簡単に記述できます。

5. 簡単なREST APIのサンプルコード（@Controllerで記述）

ここでは、Springを使って実際に動作するシンプルなREST APIを作ってみましょう。今回は「メモ情報」を扱うREST APIです。以下のような機能を実装します。

GET：すべてのメモを取得
POST：新しいメモを追加

実際のコードは次のとおりです。@RestControllerは使わず、@Controllerと@ResponseBodyで書いています。


import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.*;
import java.util.*;

@Controller
@RequestMapping("/memos")
public class MemoController {

    private List<String> memos = new ArrayList<>(List.of("最初のメモ", "Springの練習"));

    @GetMapping
    @ResponseBody
    public List<String> getMemos() {
        return memos;
    }

    @PostMapping
    @ResponseBody
    public String addMemo(@RequestParam String memo) {
        memos.add(memo);
        return "メモを追加しました：" + memo;
    }
}

このAPIを使えば、ブラウザで/memosにアクセスすることでメモ一覧を取得できますし、POSTでmemoというパラメータを送信すれば新しいメモを追加することができます。

新人

「実際に動かしてみると、JSONでレスポンスが返ってくるんですね！」

先輩

「そうそう。Springで作るREST APIは、見た目こそ地味だけど、システムの中で重要な役割を持つんだよ。」

このように、Springを使えば簡単にREST APIを作ることができます。特に@Controllerと@ResponseBodyの組み合わせを理解すれば、初心者でもすぐに基本的なAPIを実装できるようになります。

6. REST APIでよく使うアノテーション（@RequestMapping、@RequestParam、@PathVariableなど）

SpringでREST APIを作成する際に欠かせないのが、@RequestMappingや@RequestParam、@PathVariableといったアノテーションです。これらはリクエストの内容をどのように受け取るかを指定するために使います。

@RequestMappingは、どのURLに対してどのメソッドを呼び出すかを指定するアノテーションです。GETやPOSTなどのHTTPメソッドを細かく分けたい場合は、@GetMappingや@PostMappingといった専用アノテーションを使うこともできます。

@RequestParamは、URLのクエリパラメータ（?以降の部分）を受け取るために使います。例えば「/search?keyword=apple」のようなリクエストで「keyword」の値を受け取れます。

@PathVariableは、URLの一部を変数として受け取りたい場合に使います。例えば「/users/1」のようなURLで「1」という値をパラメータとして取得できます。


import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.*;

@Controller
@RequestMapping("/sample")
public class SampleController {

    @GetMapping("/greet")
    @ResponseBody
    public String greet(@RequestParam String name) {
        return "こんにちは、" + name + "さん！";
    }

    @GetMapping("/user/{id}")
    @ResponseBody
    public String getUser(@PathVariable int id) {
        return "ユーザーID：" + id;
    }
}

この例では、@RequestParamでnameというパラメータを受け取り、@PathVariableでURLの一部であるIDを受け取っています。REST APIではこれらを正しく使い分けることで、柔軟なリクエスト処理が可能になります。

7. フロントエンドからのリクエストとJSONレスポンスの流れ

実際のアプリケーション開発では、フロントエンド（HTMLやJavaScriptなどの画面側）からREST APIにリクエストを送り、Spring側でそのリクエストを受け取って処理を行い、レスポンスとしてJSON形式のデータを返すという流れが基本です。

Springでは、Javaのオブジェクトをそのまま返すと、自動的にJSON形式に変換してレスポンスとして送ってくれます。これが非常に便利な仕組みで、初心者でも複雑な変換処理を意識せずに使うことができます。

次のコードでは、オブジェクトを返すだけでSpringが自動でJSONに変換してくれます。


import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.*;

@Controller
@RequestMapping("/info")
public class InfoController {

    static class Info {
        public String title;
        public String message;

        public Info(String title, String message) {
            this.title = title;
            this.message = message;
        }
    }

    @GetMapping("/greeting")
    @ResponseBody
    public Info getInfo() {
        return new Info("お知らせ", "本日はメンテナンスがあります。");
    }
}

このコードでは、Infoというクラスのインスタンスを返していますが、ブラウザでアクセスすると自動的にJSON形式に変換されて表示されます。フロントエンドではこのレスポンスを受け取り、画面に表示したり、別の処理に使ったりすることができます。

8. よくあるトラブルとその対処法（エラーコード、URLの書き方ミスなど）

REST APIをSpringで作成するとき、初心者がよくつまずくポイントがいくつかあります。ここでは代表的なトラブルとその対処方法について解説します。

① URLの書き方ミス

よくあるのが、リクエストを送る際にURLを間違えてしまうケースです。たとえば「/users/1」というパスを想定しているのに、間違えて「/user/1」や「/users?id=1」と送ってしまうと、エラーになります。

このような場合は、エラーコード「404 Not Found」が返ってくることが多く、これは「そのURLに対応するメソッドが見つかりません」という意味です。@RequestMappingや@PathVariableのパス指定が正しいかを再確認しましょう。

② パラメータの不足

@RequestParamを使っているときに、必要なパラメータが送られてこないとエラーになります。たとえば「/greet?name=太郎」というリクエストを想定しているのに、nameがない状態でアクセスすると、「400 Bad Request」というエラーコードになります。

この場合は、@RequestParamにrequired = falseを付けるか、デフォルト値を設定することで対応可能です。


@GetMapping("/hello")
@ResponseBody
public String hello(@RequestParam(required = false, defaultValue = "ゲスト") String name) {
    return "こんにちは、" + name + "さん";
}

このように書いておくことで、nameが指定されなかった場合でも「ゲスト」という名前でレスポンスを返すようになります。

③ JSONレスポンスが文字化けする

SpringでレスポンスとしてJSONを返すときに、文字化けすることがあります。これは文字コードが正しく設定されていない場合に発生することがあります。通常はSpringが自動でUTF-8で返してくれるのですが、古い設定や独自の設定をしていると発生することがあります。

その場合は、Spring Bootであればapplication.propertiesに以下のように記述することで回避できます。


spring.http.encoding.charset=UTF-8
spring.http.encoding.enabled=true
spring.http.encoding.force=true

また、GradleでSpring Bootを使っている場合、依存関係が正しく入っているかどうかも確認しておくと良いでしょう。

④ メソッドの種類を間違える

たとえば「GET」メソッドしか受け付けないAPIに対して「POST」でアクセスすると、「405 Method Not Allowed」というエラーコードが返ります。これはそのURLは存在するが、HTTPメソッドが許可されていないという意味です。

このようなエラーが出たときは、@GetMappingや@PostMappingなどのアノテーションが正しいかどうか、フロントエンド側のリクエストが対応するメソッドで送られているかを見直しましょう。