RESTful APIのサンプル（Java）を作成する手順をご紹介

＜目次＞

(１) RESTful APIのサンプル（Java）を作成する手順をご紹介
　 (１-１) 作成するAPIの概要
　 (１-１) RESTful APIの開発用プロジェクト作成（Spring Boot）
　(１-２) リソースのクラス作成（MVCのM＝Model相当）
　(１-３) リソースのコントローラー作成（MVCのC＝Controller相当）
　(１-４) アプリケーションの実行
　 (１-５) 疎通確認

(１) RESTful APIのサンプル（Java）を作成する手順をご紹介

本記事ではJavaのフレームワークであるSpring Bootをベースに使用して、簡単な「RESTful API」を実際に作成する手順をご紹介します。

(１-０) 作成するAPIの概要

・このAPIは「/say_hello」に対する「GET」リクエストを処理します。

・オプションパラメータは「name」をクエリパラメータ（※注０）として許可します。

・GETリクエストが正常処理されたら、レスポンスコード「200 OK」を応答します。

・応答（レスポンス）のボディ部にはJSON形式で、挨拶文（Hello XXXX）を返却します。

（※注０）クエリパラメータ：サーバにデータを送るためURLの末尾に付与するパラメータ。

以下、レスポンスのボディ部の例です（JSON形式）（→★JSON記事）

（例）

{
    "id": 1,
    "content": "Hello, World!"
}

（図１００）APIのイメージ図

(１-１) RESTful APIの開発用プロジェクト作成（Spring Boot）

今回はSpring Bootのプロジェクトを使って、RESTful APIのサンプルを使用します。Spring Bootの概要やプロジェクトの作り方（Hello World）については、別途以下の記事で紹介していますので、そちらを参照頂けたらと思います。

⇒（手順）Spring Bootのプロジェクト作成～Hello Worldの手順

上記手順で、プログラムを作るための土台のプロジェクトや、ビルド（※注１）の仕組みを用意出来たので、ここからRESTful APIの実装をします。

（※注１）コンパイル済みプログラムや外部参照ファイルを集め、実行ファイルを固める処理のこと。

＞目次にもどる

(１-２) リソースのクラス作成（MVCのM＝Model相当）

まずはリソースのオブジェクトを表現するクラスを作ります（MVCのModelに相当）。このクラス自体は、変数・コンストラクタ・ゲッターメソッドがある、一般的なJavaのクラスになります。

●追加場所

プロジェクトの以下のパスに追加します。

src/main/java/com/XXXX/YYYY

※基本的に、XXXX＝Groupの「com.」以降の値、YYYY＝Artifactの値です。

（図１２１）①

プロジェクトのツリーで言うと、下記の箇所に追加する形になります。

（図１２１）②

●追加手順

・①追加対象フォルダを「右クリック」⇒「New」⇒「File」を選択

（図１２２）①

↓

・②ファイル名を「SayHello.java」として「Finish」を押下

（図１２２）②

↓

・③プログラムの追加完了

（図１２２）③

●追記するコード

（サンプル）

package com.example.restservice;
public class SayHello {

  private final long id;
  private final String content;

  public SayHello(long id, String content) {
    this.id = id;
    this.content = content;
  }

  public long getId() {
    return id;
  }

  public String getContent() {
    return content;
  }
}

（図１２３）

＞目次にもどる

(１-３) リソースのコントローラー作成（MVCのC＝Controller相当）

RESTful APIが受けるリクエストやレスポンスは、コントローラーを作って制御します。コントローラー部品には「@RestController」のアノテーションを付与します。下記のコントローラークラスが「/say_hello」に対するGETリクエストを処理します。

●追加場所

プロジェクトの以下のパスに追加します（先ほどのModelと同じ場所です）。

src/main/java/com/XXXX/YYYY/

※基本的に、XXXX＝Groupの「com.」以降の値、YYYY＝Artifactの値です。

●追加手順

・①追加対象フォルダを「右クリック」⇒「New」⇒「File」を選択

（図１３１）①

↓

・②ファイル名を「SayHelloController.java」として「Finish」を押下

（図１２２）②

●サンプルプログラム（コントローラー）

package com.example.restservice;
import java.util.concurrent.atomic.AtomicLong;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class SayHelloController {

  private static final String template = "Hello, %s!";
  private final AtomicLong counter = new AtomicLong();

  @GetMapping("/say_hello")
  public SayHello say_hello(@RequestParam(value = "name", defaultValue = "World") String name) {
    return new SayHello(counter.incrementAndGet(), String.format(template, name));
  }
}

（図１２３）

●サンプルプログラム説明

・「@GetMapping」アノテーションにより、HTTPの「GET」リクエストが「/say_hello」の「say_hello()」メソッドにマッピングされます。

・「@RequestParam」の役割はクエリパラメータ（name）を、say_hello()メソッドの引数「name」に組み込む事です。また、クエリパラメータ（name）がURLで与えられていない場合は、「defaltValue」に指定した値が使われます。

・「say_hello()」メソッドのボディ部の実装（「return new ～」の行）では、SayHelloクラスのインスタンスを生成して返却します。この中にはSayHelloクラスのメンバ変数である「id」と「name」が入っています。

ここまでで、プログラム自体の作成は完了で、後は次のステップで実行するのみです。

●（補足）従来のMVCコントローラーとRESTful APIのコントローラーの違い

上記の手順でMVCのController相当のクラスを作りましたが、これら従来のMVCのControllerと異なる点は何でしょうか？特に、HTTPレスポンスのボディ部の中身が異なります。従来のMVCでは画面描画はViewが担っており、HTMLの中に、今回で言う「Hello XXXX」の文言を埋め込んで表示していました。

（図１３３）

一方で、今回のRESTful APIおのコントローラーはオブジェクト（例：SayHello）を丸ごと、JSON形式にしてHTTPレスポンスで返却します。

（図１３４）

＞目次にもどる

(１-４) アプリケーションの実行

作成したアプリケーションを次のコマンドで起動します。

・①プロジェクト資源のあるパスに移動します。

$ cd /[プロジェクト資源のあるパス]/

私の例では他のEclipseプロジェクトと同じ階層です。フォルダの中は下図のようになっています。

（図１４１）

・②Mavenのラッパーシェル実行

上記ディレクトリ配下の「mvnw」というシェルを次のように実行します。

$ ./mvnw spring-boot:run

この「mvnw」というシェルスクリプトはMavenのラッパー（＝Mavenの機能含み、別の形態で提供する外包みのクラス・関数・ライブラリ等の事）であり、このシェルを使う事でMavenがインストールされていない環境においても、Mavenのプロジェクトを実行する事が可能になります。シェルを実行すると、正しいMavenのバージョンをホームディレクトリ等から自動で取得してくれます。

（図１４２）①

（図１４２）②

もし、起動時にエラーが出る場合は以下の記事もご参照ください。

⇒（参考）mvnwでMavenアプリケーション起動時のエラー対処方法（★エラー）

＞目次にもどる

(１-５) 疎通確認

ブラウザから次のようなURLで、JSON形式の応答が返ってくれば成功です。

http://[サーバのホスト名]:8080/say_hello

（図１５１）

URLの最後にクエリパラメータ「name=XXXX」を追加して反映される事も確認します。

http://[サーバのホスト名]:8080/say_hello?name=XXXX

（図１５２）

＞目次にもどる