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

新人

「先輩、最近よく聞くREST APIって何なんですか？Spring Bootで簡単に作れるって聞いたんですけど…」

先輩

「いい質問だね。REST APIは、Webシステムやアプリ同士がデータをやり取りするための仕組みなんだ。Spring Bootは、そのREST APIを効率よく作るために便利なフレームワークだよ。」

新人

「JavaでWebページは作ったことあるけど、APIって画面がないからイメージしづらいです…」

先輩

「確かに最初はそう感じるかもね。でも、Spring Bootを使えば初心者でもREST APIの作り方を理解しやすいよ。これから順を追って解説していこう！」

1. REST APIとは何か？（基本概念と仕組み）

REST API（レストエーピーアイ）とは、インターネット上でデータをやり取りするための設計ルールのことです。特にWebアプリケーション同士が「情報をください」「この情報を更新して」などとやりとりするために使われます。

RESTとは「Representational State Transfer（表現状態の転送）」の略で、HTTPという通信の仕組みを使って、リソース（データ）を操作します。たとえば、「ユーザー一覧を取得する」「商品を登録する」といった操作を行うのに適しています。

REST APIは、次のようなHTTPメソッドを使ってリクエストを送信します：

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

これらの操作をURLに対して行うことで、画面を持たないシンプルな通信が可能になります。

たとえば、次のようなURLとメソッドの組み合わせが一般的です：

GET /users → ユーザー一覧の取得
POST /users → ユーザーの新規作成
PUT /users/1 → IDが1のユーザー情報の更新
DELETE /users/1 → IDが1のユーザーを削除

画面表示がないぶん、スマートフォンアプリやJavaScriptからの非同期通信にぴったりの設計です。

2. REST APIをSpring Bootで作る際の全体の流れ（初期理解）

それでは、実際にSpring BootでREST APIを作成する流れをざっくりと説明しましょう。

今回は、初心者の方が入りやすいように、次のような環境で開発します。

pleiades（プレアデス）でSpring Bootプロジェクトを作成
依存関係は、チェックボックスでSpring Webのみ追加
ビルドツールはGradleを選択（Mavenは使用しない）
コントローラは@Controllerを使って実装
@RestControllerは使わない
Bootstrapなどの外部ライブラリは使わない

基本的な開発のステップは以下の通りです：

Spring Bootプロジェクトの作成（pleiadesから）
Controllerクラスの作成
URLとメソッドのマッピング
レスポンスをViewではなく、文字列として返すように設計
ブラウザやPostmanなどで動作確認

まず、pleiadesのメニューから「ファイル > 新規 > Spring Starterプロジェクト」を選択します。次に、使用する依存関係として「Spring Web」にチェックを入れてください。

作成したプロジェクトに、次のような@Controllerクラスを追加します。


package com.example.demo.controller;

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 hello() {
        return "こんにちは、Spring BootのREST APIへようこそ！";
    }
}

@Controllerと@ResponseBodyを組み合わせることで、HTMLではなく文字列をそのままレスポンスとして返すことができます。

ここで@RestControllerを使えばもっとシンプルに書けますが、今回は@Controllerのみを使用するという前提のため、あえてこの方法を選んでいます。

上記のコードを記述してSpring Bootアプリケーションを起動すると、ブラウザで「http://localhost:8080/hello」にアクセスすることで、次のような文字列が表示されます。


こんにちは、Spring BootのREST APIへようこそ！

このように、画面を使わずに文字列を返すことで、APIとしてのレスポンスを確認することができます。

今後はこの仕組みを拡張して、ユーザー情報や商品データなどを扱うREST APIを作成できるようになっていきます。

3. REST APIの基本的な作り方（プロジェクト作成〜Controller作成）

Spring BootでREST APIを作成するには、まずプロジェクトの土台となる環境を用意する必要があります。ここでは初心者向けに、pleiades（プレアデス）を使ったプロジェクトの作成手順から説明します。

まずはpleiadesを起動し、「ファイル > 新規 > Springスタータープロジェクト」を選択してください。

表示されるウィザードで、以下のように設定します：

名前：任意（例：rest-api-demo）
Group：com.example
Artifact：demo
Type：Gradle Project（MavenではなくGradleを選択）
Java Version：Java 17など任意
Dependencies（依存関係）：「Spring Web」にチェックを入れる

依存関係は、Spring Webだけで構いません。他の技術（JPAやSecurityなど）は今回は使いません。

プロジェクトを作成すると、Spring Bootが自動的に初期構成された状態になります。この状態で、すぐにコントローラクラスを作ってREST APIのエンドポイントを実装できます。

4. コントローラクラスの実装方法（@Controllerを使ったGETメソッドの書き方）

Spring BootでREST APIの入り口となるのがController（コントローラ）クラスです。コントローラは、URLとメソッド（GETやPOST）を紐づけることで、APIの処理を定義します。

今回は@Controllerを使い、@RestControllerは使わない前提です。そのため、レスポンスとして文字列を返すには@ResponseBodyを組み合わせて記述します。

以下は、簡単なGETメソッドを実装した例です。


package com.example.demo.controller;

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

@Controller
public class SampleController {

    @GetMapping("/api/message")
    @ResponseBody
    public String message() {
        return "これはSpring Bootで作成したサンプルAPIです。";
    }
}

@GetMapping("/api/message")は、「/api/message」というURLにGETリクエストが来たときに、message()メソッドを実行するよう指定しています。

@ResponseBodyを使うことで、HTMLテンプレートを返すのではなく、文字列（JSONなども対応可能）をそのままレスポンスとして返します。

このControllerクラスを作成したら、Spring Bootアプリケーションを実行し、http://localhost:8080/api/messageにアクセスすることで、次のようなメッセージが表示されます。


これはSpring Bootで作成したサンプルAPIです。

このように、画面のないAPIでもURLにアクセスすることで処理の確認が可能です。今後はここにロジックを追加したり、データベースと連携したりすることで、より実践的なREST API開発へと進化させていきます。

5. application.properties の基本設定

Spring Bootでは、アプリケーションの設定をまとめるファイルとしてapplication.propertiesがあります。このファイルに設定を書き加えることで、ポート番号や文字コードなど、さまざまな動作を変更できます。

たとえば、標準ではWebアプリケーションのポートは8080ですが、これを変更したい場合は以下のように記述します。


server.port=9090

上記の設定により、http://localhost:9090でアプリが動作するようになります。

次に、APIレスポンスで文字化けを防ぐために、UTF-8での出力を指定する設定も紹介します。


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

この設定を追加しておくと、日本語のメッセージが正しく表示されるようになります。

また、Spring BootではThymeleafやFreemarkerのテンプレートを使わずにREST APIを作成することが多いため、Viewの設定やテンプレートエンジンの設定は不要です。

初心者がつまずきやすいポイントとして、「エラーが出るのに原因がわからない」という問題があります。その際は、このapplication.propertiesの設定ミスが影響していることもありますので、丁寧に設定内容を確認するようにしましょう。

なお、プロパティファイルはプロジェクト内の以下の場所にあります：


src/main/resources/application.properties

このファイルに必要な設定を順に追加していけば、Spring BootのREST APIを安定して運用できるようになります。

6. パスやURLマッピングの基本（@RequestMapping/@GetMappingなど）

Spring BootでREST APIを開発する際には、URLと処理を結びつけるマッピングがとても重要です。これは、どのURLにアクセスしたら、どのメソッドを実行するかを決める仕組みです。

初心者が最初につまずきやすいのが、@GetMappingや@RequestMappingといったアノテーションの使い方です。

@GetMappingは、特定のURLに対して「GET」リクエストが来たときに処理を行うためのものです。一方、@RequestMappingは、GETやPOSTなど複数のリクエスト方法に対応できます。

例として、次のようなコードを見てみましょう。


@Controller
public class PathController {

    @GetMapping("/api/info")
    @ResponseBody
    public String getInfo() {
        return "GETメソッドで取得した情報です";
    }

    @RequestMapping("/api/common")
    @ResponseBody
    public String getCommon() {
        return "このメソッドはGETでもPOSTでもアクセス可能です";
    }
}

@GetMapping("/api/info")は、http://localhost:8080/api/infoにアクセスしたときだけ動作します。一方、@RequestMapping("/api/common")は、リクエストの種類に関係なく呼び出されます。

ただし、@RequestMappingを使う場合は、必要に応じてmethod属性を指定するのが安全です。明示的にmethod = RequestMethod.GETと書くことで、意図しない動作を防ぐことができます。

7. ブラウザで確認する方法と簡単なデバッグ方法

作成したREST APIが正しく動いているかを確認するには、ブラウザでURLにアクセスするのが最も簡単です。たとえば、@GetMapping("/api/hello")と書いた場合は、http://localhost:8080/api/helloにアクセスするだけでOKです。

文字列がブラウザにそのまま表示されれば、Spring BootのREST APIが正しく動いている証拠です。

さらにもう一歩踏み込んで確認したい場合は、次のような方法があります：

ブラウザの開発者ツール（F12キー）を使い、ネットワークタブでリクエストとレスポンスを確認する
pleiadesのコンソール出力で、どのURLが呼び出されたかやエラーが出ていないかを確認する

これだけでも十分にデバッグできますが、もっと細かく確認したい場合は、ログにメッセージを出力しても良いでしょう。

たとえば、次のようにSystem.out.println()を使う方法があります。


@GetMapping("/api/test")
@ResponseBody
public String test() {
    System.out.println("テストメソッドが呼ばれました");
    return "テスト成功";
}

このようにして、初心者でも目に見える形で動作確認ができるので安心です。画面のないAPI開発でも、URLと文字列のレスポンスだけでしっかりと確認ができるのがREST APIの良いところです。

8. REST API開発のよくある失敗例とその対策（@RestControllerではない点の注意含む）

Spring BootでREST APIを開発する際、初心者がよくつまずくポイントがいくつかあります。ここでは、実際によくある失敗例と、その対処法を解説します。

① @Controllerを使っているのに画面が表示されない

REST APIでは、画面を表示するのではなく文字列やデータを返すことが目的です。しかし、@Controllerを使っていても、@ResponseBodyを忘れてしまうと、「テンプレートファイルが見つからない」というエラーが出ることがあります。

これは、Springが「HTML画面を返すもの」と誤解してテンプレートエンジンを探してしまうためです。

対策：必ず@ResponseBodyをつけるようにしましょう。


@Controller
public class MyController {

    @GetMapping("/api/check")
    public String noBody() {
        return "これは失敗例です"; // → エラーになる可能性大
    }
}

上記はテンプレートを探してしまうため、文字列として返したい場合は以下のように修正が必要です。


@GetMapping("/api/check")
@ResponseBody
public String correct() {
    return "正しいレスポンスです";
}

② @RestControllerを使えば動いたけど…

調べていると「@RestControllerを使えば簡単」と紹介されていることがあります。たしかにそのとおりで、@ResponseBodyを明示しなくても動作します。

ですが、この記事では@Controllerのみを使う前提です。そのため、他サイトの情報をうのみにせず、@Controller + @ResponseBodyという組み合わせを正しく理解しておくことが大切です。

③ URLが間違っている

意外に多いのが、URLを入力する際のミスです。@GetMapping("/api/sample")と定義したのに、http://localhost:8080/sampleと入力してしまうパターンです。

対策：URLのパスは@GetMappingで指定した文字列と完全一致でないと反応しません。api/を忘れたり、/が抜けていたりするとアクセスできないので注意しましょう。

④ POSTやPUTで確認しようとしてしまう

ブラウザは基本的に「GETリクエスト」しか送れません。つまり、@PostMappingや@PutMappingの確認はブラウザではできないのです。

対策：GETメソッドだけでなく、POSTやPUTを確認したい場合は「Postman」などのツールを使いましょう。初心者でもボタン操作でリクエストを送れるのでおすすめです。

⑤ 文字化けしてしまう

APIで日本語を返そうとしたときに、文字化けが起きることがあります。これはapplication.propertiesで文字コードの設定がされていない場合によく起こります。

対策：前の章で紹介したように、UTF-8を指定しておくことで回避できます。


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

これらの対策を押さえておくだけで、Spring BootのREST API開発をスムーズに進めることができます。特に初心者の方は、ひとつずつ動作を確認しながら開発する姿勢が大切です。

この記事を読んだ人からの質問

Spring BootでREST APIを作る（基本）初心者向けの作り方をやさしく解説！