【ITニュース解説】Leveling Up: Returning JSON in my first Spring Boot REST API

システムエンジニアを目指す皆さんにとって、Webサービスやアプリケーション開発は非常に興味深い分野だろう。その中でも、現代のアプリケーション開発に欠かせない技術の一つが「API（Application Programming Interface）」、特に「REST API」だ。今回紹介するニュース記事は、まさにこのREST APIをSpring Bootという人気のフレームワークを使って開発する上での、重要な一歩を解説している。

記事の筆者は、Spring Bootで最初に「/hello」というシンプルなエンドポイント（特定の機能を提供するURLのこと）を作成した後、それをより実用的なものにしたいと考えた。最初の段階では、ただ「Hello World!」のような短いテキストを返すだけでも学習には十分だが、実際のWebサービスでは、単なるテキストではなく、もっと整理された「構造化されたデータ」を返すことが一般的だ。今回取り組んだのは、その構造化されたデータとして広く使われている「JSON（JavaScript Object Notation）」形式のデータをAPIから返せるようにすることだった。

では、なぜ単なるテキストではなくJSONが必要なのだろうか。例えば、あなたが天気予報のAPIを利用するとしよう。もしAPIが「今日の天気は晴れ、最高気温は25度、降水確率は10%です」という単なるテキストを返してきたらどうだろう。人間が読むには問題ないが、この情報の中から「最高気温」だけをプログラムで取り出して表示したい場合、テキストを解析して「25度」という部分を探し出すのはかなり手間がかかる。もしこの情報が「{"天気": "晴れ", "最高気温": 25, "降水確率": 10}」というJSON形式で返ってきたら、プログラムは「最高気温」というキーに対応する値「25」を簡単に、かつ正確に取り出すことができる。これが、構造化されたデータを使う大きな理由だ。JSONは、人間にとっても読みやすく、コンピュータープログラムにとっても扱いやすい、非常に優れたデータ交換フォーマットとして、Web APIの分野でデファクトスタンダードになっている。

記事の筆者が行った作業は、大きく二つのステップに分けられる。

一つ目のステップは、「シンプルなレスポンスクラス」を作成したことだ。これはJavaのクラスであり、APIがクライアントに返すデータの「型」を定義する役割を持つ。例えば、今回のAPIが「メッセージ」と「ステータス」という二つの情報を返したい場合、このクラスの中に「String message;」と「String status;」という形で、それぞれの情報を保持するための変数（フィールド）を定義する。このクラスは、まさにJSONデータの「設計図」のようなものだと考えるとわかりやすい。Spring Bootのようなフレームワークでは、このようなJavaのクラス（専門的にはPOJO: Plain Old Java Objectと呼ばれることが多い）を定義しておくと、後述するコントローラーがこのクラスのオブジェクトを返したときに、フレームワークが自動的にそのオブジェクトをJSON形式の文字列に変換してくれるのだ。開発者が手動でJSONの記法に沿った文字列を作成する手間を省けるため、非常に効率的だ。

二つ目のステップは、「コントローラーを更新して、このオブジェクトを返すように変更したこと」だ。Web APIにおけるコントローラーとは、クライアントからのHTTPリクエスト（例えばWebブラウザからのアクセスや、スマートフォンアプリからのデータ要求など）を受け取り、そのリクエストに応じた処理を実行し、最終的にクライアントへHTTPレスポンス（処理結果のデータ）を返す中心的な役割を担う部分だ。

具体的には、記事の筆者は、以前は単なるテキストを返していたメソッド（特定の処理を行うコードのまとまり）を、新しく作成したレスポンスクラスのオブジェクトを返すように修正した。例えば、以前は「String」型を返していたところを、新しく作った「MyResponseClass」型を返すように変更し、そのメソッド内で「new MyResponseClass("成功しました", "OK")」のようにオブジェクトを生成し、それを返すようにしたわけだ。

ここでSpring Bootが提供する強力な機能が発揮される。Spring Bootは、コントローラーのメソッドがJavaオブジェクトを返すと、自動的にそのオブジェクトをJSON形式に変換し、HTTPレスポンスのボディに含めてクライアントに送信してくれる。この自動変換は、Spring Bootに組み込まれている「HTTPメッセージコンバータ」という仕組みによって実現されている。開発者はJSON形式の文字列を意識することなく、Javaのオブジェクトを扱う感覚でAPIのレスポンスを定義できるため、開発の生産性が格段に向上する。

結果として、APIにアクセスしたクライアントは、以前のようなプレーンテキストではなく、以下のような構造化されたJSONデータを受け取ることができたはずだ。

Copy
1{
2  "message": "Hello from Spring Boot API!",
3  "status": "SUCCESS"
4}

これは、まさに実世界のWebサービスが情報をやり取りする際の標準的な形式だ。例えば、スマートフォンアプリがこのAPIにアクセスした場合、アプリは受け取ったJSONデータの中から「message」というキーの値を取り出して画面に表示したり、「status」が「SUCCESS」であることを確認して次の処理に進んだりすることができる。プログラムにとって非常に扱いやすい形式なのである。

今回の学習は、Spring Bootを使ってREST APIを開発する上で、非常に実用的な知識と経験を与えてくれるものだ。単に動くAPIを作るだけでなく、それが「実世界でどのように使われるか」を意識した一歩を踏み出したと言えるだろう。システムエンジニアとしてキャリアをスタートさせる皆さんにとって、このようなデータの構造化と、フレームワークが提供する自動変換の仕組みを理解することは、今後のAPI開発において基盤となる重要なスキルとなるだろう。Spring Bootは、このような複雑な処理を抽象化し、開発者がビジネスロジックに集中できるような便利な機能が豊富に用意されている。今後も様々な機能を学びながら、より高度なWebサービス開発に挑戦していくことをお勧めする。