ThymeleafはHTMLを動的に生成してWeb上に表示する方法でした。しかし、近年のWeb開発では、画面ではなく”データ”を返すAPIの重要性が高まっています。この記事では、HTMLではなくJSON形式でデータをやりとりするREST APIの基本構成について解説します。

　「RESTって何？」「@RestControllerってどう使うの？」「JSONって聞いたことあるけどよくわからない…」という方でも大丈夫！この記事を読み終える頃には、Spring BootでシンプルなREST APIを作ってJSONで入出力できるようになります。

REST APIとは？Thymeleafとの違いからスタート

　Thymeleafでは、ControllerからHTMLテンプレート（View）を返していました。一方、REST APIはデータだけ（主にJSON形式）を返す仕組みです。

• Thymeleaf＝サーバ側でHTMLを生成してブラウザに渡す
• REST API＝データだけを渡して、画面はフロントが作る

　このような違いからバックエンドとフロントエンドの分業が進んでいる現代のWebアプリ開発では、REST APIがその橋渡し役として非常に重要な存在です。

それぞれの特徴を下記の表にまとめます：

　これにより、Thymeleafで構築した画面とは異なり、非同期通信やフロントエンド連携に強い構成が可能になります。特にSpring Bootはサーバーサイド（バックエンド）を担うことが多く、フロントエンドはReact、Vue、AngularなどのJavaScriptフレームワークが担当するケースが一般的です。そのため、HTMLテンプレートエンジンであるThymeleafの利用比率は下がりつつあり、代わりにREST APIによるデータ通信が主流になってきています。

💡 バックエンドとフロントエンドの違い

フロントエンド：ユーザーが直接目にする「画面」や「操作」の部分を担当します。HTML/CSS/JavaScriptで構築され、ReactやVue、Angularなどのフレームワークが使われます。

バックエンド：データの取得・保存・処理といった裏側のロジックを担当します。Spring BootやNode.js、Ruby on Railsなどの技術で構築され、主にREST APIなどを通じてフロントエンドにデータを提供します。

HTTPメソッドの基本：GET/POST/PUT/DELETEの役割

　REST APIでは、HTTPメソッドを使ってリソース（データ）に対する操作を表現します。

• GET：データの取得
• POST：データの新規作成
• PUT：データの更新
• DELETE：データの削除

それぞれの操作に適切なメソッドを使うことで、APIの意味が明確になります。

💡 補足メモ：実務ではPOSTで更新することも多い
RESTの原則では更新にPUTを使うのが正しいとされていますが、実際の開発現場ではPOSTで更新処理を行うケースも一般的です。理由としては、PUTがブラウザのフォームで直接使いにくいことや、アプリ側で柔軟に処理をまとめたいケースが多いことが挙げられます。

@RestControllerと@ResponseBodyの関係

　Thymeleafでは@Controllerを使っていましたが、REST APIでは@RestControllerを使います。これは、クライアントに画面（HTML）ではなくデータ（主にJSON）を返すための設計に適したアノテーションです。

@RestController
public class HelloController {
    @GetMapping("/hello")
    public String hello() {
        return "Hello, JSON!";
    }
}

↓↓↓↓↓　以下と同じ意味　↓↓↓↓↓

@Controller
@ResponseBody
public class HelloController {
    @GetMapping("/hello")
    public String hello() {
        return "Hello, JSON!";
    }
}

　@ResponseBodyは、メソッドの戻り値をViewとして解釈せず、HTTPレスポンスのボディとしてそのまま返すようSpringに指示するアノテーションです。このように、@RestControllerは @Controller と @ResponseBody を組み合わせたものであり、すべてのメソッドの戻り値を自動的にJSONなどのレスポンスとして処理してくれる便利な仕組みです。REST APIでは、基本的に画面を返さずJSONを返すことが多いため、@RestControllerを使うのが定番です。

JSONって何？HTMLではなくJSONを返す理由

　JSON（JavaScript Object Notation）は、データを軽量なテキスト形式で表現するフォーマットであり、構造化された情報を簡単に表現できます。key-value形式で人にも読みやすく、機械による処理にも適しているため、Web APIの標準的なフォーマットとして広く使われています。

　ThymeleafはHTMLテンプレートを返すことで、ユーザーにとって見やすい画面を構築しますが、REST APIではそのような画面を返さず、機械が処理しやすいデータ（JSON）だけを返すことに特化しています。

　このようにHTMLではなくJSONを返すことで、JavaScriptやモバイルアプリ、外部システムなどがデータを受け取りやすくなり、より柔軟で再利用性の高いアーキテクチャを実現できます。特にフロントエンドがReactやVueなどのライブラリで構築される現在の開発環境では、JSON形式のデータをやりとりする設計が主流となっています。

REST APIでは、以下のようなデータだけを返します：

{
  "user": {
    "id": 101,
    "name": "Taro Yamada",
    "email": "taro@example.com"
  },
  "status": "success",
  "timestamp": "2025-08-02T14:30:00Z"
}

REST APIのレスポンス構築する

まずは、文字列を返すだけの最小限のREST APIを作ってみましょう。

@RestController
public class HelloApiController {
    @GetMapping("/api/hello")
    public String hello() {
        return "Hello, JSON!";
    }
}

▶︎ /api/helloにGetリクエストを行ったレスポンス：

Hello, JSON!

　この時点では、文字列がそのまま返るだけですが、次にMap形式で複数のデータを含むJSONを返すようにしてみましょう。Map<String,Object>型のHashMapを作成し、そこに値を入れていきます。

@RestController
public class HelloApiController {
    @GetMapping("/api/hello")
    public Map<String, Object> hello() {
        Map<String, Object> response = new HashMap<>();
        response.put("message", "Hello, JSON!");
        response.put("timestamp", LocalDateTime.now().toString());
        return response;
    }
}

▶︎ /api/helloにGetリクエストを行ったレスポンス：

{
  "message": "Hello, JSON!",
  "timestamp": "2025-08-02T15:00:00"
}

これで、複数のフィールドを含むJSONレスポンスになります。

さらにもう一歩進めて、専用のDTOクラスを使って整った構造で返すようにしてみましょう。

💡 DTOとは？
DTO（Data Transfer Object）は、外部とのデータのやり取りを目的として定義するクラスです。エンティティ（DBと直接対応するクラス）とは分けることで、APIの入出力仕様を明確に保ちつつ、セキュリティや構造の安定性も向上させる効果があります。

@RestController
public class HelloApiController {
    @GetMapping("/api/hello")
    public HelloResponse hello() {
        return new HelloResponse("Hello, JSON!", LocalDateTime.now().toString());
    }
}

// Helloのレスポンスを作るDTOクラス
public class HelloResponse {
    private String message;
    private String timestamp;

    public HelloResponse(String message, String timestamp) {
        this.message = message;
        this.timestamp = timestamp;
    }

    // getter, setter
}

▶︎ /api/helloにGetリクエストを行ったレスポンス：

{
  "message": "Hello, JSON!",
  "timestamp": "2025-08-02T15:00:00"
}

　このようにレスポンスで渡したい値をクラス（DTO）にまとめることで、簡単にJsonに変換して渡すことができます。またこのDTOクラスは、フィールドに別のDTOクラスを持つことも可能で、複雑なレスポンスを構築することもできます。

💡 補足：戻り値にオブジェクトを指定するだけでJSONに変換される
Spring Bootでは、@RestControllerのもとでメソッドの戻り値にオブジェクトを指定すると、自動的にJSON形式に変換されてレスポンスとして返されます。これは、Springが内部でJacksonというライブラリを使ってシリアライズ処理を行ってくれるためです。

リクエストの受け取り：@RequestBodyでJSONをJavaに変換する

　クライアントから送られてくるJSON形式のデータをJavaで受け取るには、@RequestBodyアノテーションを使います。これは、リクエストのBody部分に含まれるJSONを、自動的にJavaオブジェクトに変換してくれる便利な仕組みです。

　まずは、名前だけを受け取る最も簡単な例から見てみましょう：

@PostMapping("/api/user")
public String createUser(@RequestBody String name) {
    return "Hello, " + name;
}

▶ /api/userにリクエストボディを設定してPostリクエストを行ったレスポンス：

"Taro"

　このように、文字列を直接受け取ることもできますが、現実的には複数の項目をまとめて送るケースが多いため、Map形式で受け取る方法に修正してみます：

@PostMapping("/api/user")
public String createUser(@RequestBody Map<String, String> payload) {
    return "Hello, " + payload.get("name");
}

▶ /api/userにリクエストボディを設定してPostリクエストを行ったレスポンス：

{
  "name": "Taro"
}

この場合だと、どんな値でもpostリクエストによって受け付けている状態になってしまっています。リクエストボディのJsonの取得についてもDTOが有効です。@RequestBodyのアノテーションをつけることで、自動でDTOクラスのオブジェクトを生成してくれます。

@PostMapping("/api/user")
public String createUser(@RequestBody UserDto user) {
    return "Hello, " + user.getName();
}

public class UserDto {
    private String name;
    private String email;

    // getter, setter
}

▶ /api/userにリクエストボディを設定してPostリクエストを行ったレスポンス：

{
  "name": "Taro",
  "email": "taro@example.com"
}

　このように、DTOクラスを使うことで、リクエストパラメータの構造が明確になり、バリデーションや整合性チェックなども容易になります。@RequestBodyを使えば、SpringがJacksonを使ってJSON→Javaオブジェクトへの変換を自動で行ってくれるため、開発者はビジネスロジックに集中することができます。

⚠️ DTOクラスにはgetter/setterを設定しよう！
Spring Bootが内部でJacksonを用いてJSONとJavaオブジェクトを相互変換する際、JavaBeansの仕様に従ってプロパティへアクセスします。つまり、privateフィールドに直接アクセスするのではなく、getterとsetterメソッドを通じて値を取得・設定する必要があるのです。これにより、安全で柔軟なデータバインディングが可能になります。

もしgetter/setterが存在しない場合、Jacksonはフィールドにアクセスできず、値が正しくバインドされなかったり、例外が発生することがあります。

REST APIの送受信を試すための定番ツール4選

① Postman（GUIで使える定番のAPIテストツール）

　リクエストの作成、パラメータの設定、レスポンス確認など、視覚的に直感的な操作が可能です。初心者にもおすすめで、チームでのAPI設計・テストにも適しています。

② curl（コマンドラインで使える軽量ツール）

　ターミナルから簡単にAPIを試せるツールです。スクリプトにも組み込みやすく、サーバーサイドや自動化にもよく使われます。

③ Thunder Client（VSCode拡張）

　Visual Studio Code上で動作する軽量なAPIクライアントで、開発環境と一体化して作業がスムーズに行えます。

④ Swagger UI（APIドキュメントと操作画面が一体化）

　OpenAPI仕様に基づいて自動生成されたAPIドキュメントから、そのままAPIを試すことができます。Spring Boot + Springdoc-openapiなどで簡単に導入でき、開発者にも非エンジニアにも便利です。

　それぞれ用途に合わせて使い分けることで、効率よくAPIの開発・検証が行えます。

まとめ

　この記事では、REST APIの基本的な考え方から、Spring Bootを使った実装方法、JSONでのデータのやり取りについて学びました。

• REST APIはHTMLではなくデータ（JSON）を返す仕組み
• @RestControllerを使うと、返却値がJSONになる
• @RequestBodyでJSONを受け取り、Javaオブジェクトに変換できる
• Postmanなどを使うことで、簡単にAPIの動作を確認できる

　ThymeleafでHTMLを返すのとは違い、REST APIでは他システムやJavaScriptとの通信が可能になります。これにより、フロントエンドとの連携やスマホアプリとの接続など、アプリケーションの幅が広がっていきます。

　次回は、REST APIで扱うデータをデータベースに保存したり、更新したりする「CRUD処理」に進んでいきましょう！