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

新人

「先輩、最近よく聞く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を作成するための基本的な考え方から、実際のControllerクラスの書き方、URLマッピング、設定ファイルの役割、動作確認の方法、そして初心者がつまずきやすい失敗例までを、順を追って解説してきました。REST APIという言葉は難しく聞こえがちですが、実際には「URLにアクセスするとデータや文字列が返ってくる仕組み」を理解することが第一歩です。画面を表示しないという点に戸惑う方も多いですが、Spring Bootを使えば、Controllerとアノテーションを正しく組み合わせるだけで、シンプルなAPIをすぐに作ることができます。

特に重要なのは、@Controllerと@ResponseBodyの関係です。@RestControllerを使わない場合、レスポンスとして文字列やデータを返すには@ResponseBodyが必須になります。この仕組みを理解していないと、テンプレートが見つからないエラーや、意図しない画面遷移に悩まされることになります。今回のように、あえて@Controllerを使う構成で学習することで、Spring Boot内部の動きをより深く理解できるようになります。

また、URLマッピングの考え方もREST API開発では欠かせません。@GetMappingや@RequestMappingを使って、どのURLに対してどの処理が実行されるのかを明確に定義することで、後からコードを見直したときにも分かりやすい構成になります。特に初心者のうちは、URLの入力ミスやパスの指定間違いによって「動かない」と感じる場面が多くなりますが、アノテーションの指定とブラウザで入力するURLを一つずつ丁寧に確認することが大切です。

application.propertiesの設定も、REST APIを安定して動かすための重要なポイントです。ポート番号の変更や文字コードの指定は、一見地味な作業に思えますが、日本語を扱うAPIでは特に影響が大きくなります。文字化けが発生した場合でも、設定ファイルを見直すことで簡単に解決できるケースが多いため、設定の意味を理解しながら記述する習慣を身につけておくと良いでしょう。

デバッグや動作確認についても、難しいツールを使わなくても、まずはブラウザでアクセスしてレスポンスを確認するだけで十分です。GETメソッドであればURLにアクセスするだけで結果を確認できるため、初心者でも安心して試すことができます。さらに、コンソールへの出力を活用すれば、どの処理が実行されているのかを目で追いながら確認でき、理解が深まります。

今回紹介した内容は、Spring BootでREST APIを作るうえでの土台となる部分です。この基礎をしっかり押さえておけば、今後データベースと連携したり、JSON形式でデータを返したりといった、より実践的なAPI開発にもスムーズに進むことができます。まずはシンプルなAPIを何度も作り、URLとレスポンスの関係を体で覚えることが、理解への近道です。

まとめとしてのサンプルプログラム

ここで、これまで学んだ内容を振り返るための、シンプルなREST APIのサンプルをもう一度確認してみましょう。@Controllerと@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 SummaryController {

    @GetMapping("/api/summary")
    @ResponseBody
    public String summary() {
        return "Spring BootでREST APIの基本を学びました";
    }
}

このコードを実行し、http://localhost:8080/api/summary にアクセスすると、画面を持たないAPIとして文字列がそのまま表示されます。この「URLにアクセスすると結果が返ってくる」という感覚を掴めれば、REST APIの基本は理解できたと言えるでしょう。


Spring BootでREST APIの基本を学びました

先生と生徒の振り返り会話

生徒

「最初はREST APIって難しそうだと思っていましたが、URLにアクセスして文字が返ってくるだけだと考えると、少し身近に感じられるようになりました。」

先生

「その感覚はとても大事だね。最初から複雑なことを考えず、まずはURLとレスポンスの関係を理解することが、Spring BootでのREST API学習の第一歩なんだ。」

生徒

「@Controllerと@ResponseBodyを組み合わせる理由も、ようやく分かってきました。付け忘れるとエラーになる意味も納得です。」

先生

「うん、それを理解できれば大きな前進だよ。仕組みを知っていると、エラーが出ても落ち着いて原因を探せるようになる。」

生徒

「application.propertiesの設定も、ただ書くのではなく、何のために設定しているのかを意識するようにします。」

先生

「それができれば、次はデータベース連携やJSONレスポンスにも挑戦できるね。今回の基礎をしっかり身につけて、少しずつステップアップしていこう。」

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

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