会社で新しいプロジェクトが立ち上がってWebAPIを作ることになったけど作り方がわからない。WebAPIつくってみたいけど大変そうだな。
あと、作ったあとのドキュメントのメンテナンスとか面倒だし何かいい方法ないかな。
こんな悩みに答えます。
今回はWeb APIの作り方として、 App Engine上で稼働する「Cloud Endpoints Framework for Java」を使って解説します。また、ドキュメントのメンテナンスとしてGCP上で確認できるデベロッパーポータルの解説をします。
開発プラットフォームにGoogle Cloud Platform(以下、GCP)を使っていきます。
目次
WebAPIの作り方
それでは早速WebAPIをつくっていきましょう。
今回作るWebAPIはREST APIに則って単純なリクエストを受け取りメッセージを返すようなAPIを目指します。
ポイントをまとめるとこんな感じです。
- Cloud Endpoints Frameworkとは
- 開発の準備
- コードの実装
- 動作の確認
Cloud Endpoints Framework for Javaを使いましょう
Web API開発にはフレームワークを使って開発していきましょう。
フレームワークを使うことで技術的なリスクや煩わしさを減らすことができるので、実装に集中することができます。
今回はCloud Endpoints Framework for Javaで開発を進めていきます。
Cloud Endpoints Frameworkとは…
App Engineの標準環境であるPython、Javaのランタイムに対応するWebフレームワークです。HTTPリクエストとレスポンス通信の処理を行い、リクエストのURLを適切にコード内の関数にルーティングします。また、戻り値をJson形式に自動変換してレスポンスを送信します。
小難しいこと書いてありますが、HTTP等の通信を特に気にしなくても良しなにアクセス処理してくれますよ。ということです。
開発の準備
開発の準備をしていきます。
今回はGCPを使った開発ですので事前にGCPプロジェクトの準備(https://www.apps-gcp.com/gcp-startup/)を行ってください。
開発ツールは以下を使用します。
・Java 1.8
・Maven 3.0
・Git
・gcloudコマンド
gcloudはCLIツールです。App Engine アプリケーションのデプロイなどの作業を行うために使います。こちら(https://cloud.google.com/sdk/docs/quickstarts?hl=ja)からインストールをできます。
コードを書きましょう
それでは、実際にコードを書いていきます。
3ステップで作っていきます。
ステップ1: ベースとなるアプリケーションをgit cloneします
ステップ2: リクエストを受け付けるプログラムを書きます
ステップ3: 設定ファイルを変更します
具体的にプログラムで書かなけれならいないところとしては、「リクエストを受け付けるところ」です。
ステップ1
Googleが公開している雛形アプリケーションを取得します。
$ git clone https://github.com/GoogleCloudPlatform/java-docs-samples
$ cd java-docs-samples/appengine-java8/endpoints-v2-skeleton
ステップ2
雛形アプリケーションに用意されている下記のファイルを開きます。
・src/main/java/com/example/skeleton/MyApi.java
クラスの中身は空っぽですね。
ここにリクエストに応じたメソッドを追加していきます。
下記のように編集して保存してください。
package com.example.skeleton;
import com.google.api.server.spi.config.*;
import javax.inject.Named;
@Api(name = "myFirstApi", version = "v1")
public class MyApi {
@ApiMethod(httpMethod="get", path="/hello/{name}")
public Message hello(@Named("name") String name) {
return new Message("Welcome! " + name);
}
class Message {
private String message;
public Message(String message) {
this.message = message;
}
public String getMessage() {
return message;
}
}
}
これで、 /hello/文字列
へGETアクセスをするとhelloメソッドの処理が行われるようになります。
プログラムの解説です。
メソッド
処理を行いたいメソッドに対して @ApiMethod
アノテーションを付与することでリクエストとプログラムをマッピングすることができます。
- アノテーションの引数
- httpMethod
HTTPメソッド(GET, POST, PUT, DELETEなど)を指定します。 - path
リクエストのURIを指定ます。中括弧で囲むことで変数として扱うことができます。
- httpMethod
メソッド引数
パスに含まれる変数はメソッドの引数に @Named
アノテーションを付与することで取得することができます。パスのみならずクエリーパラメータも同様に取得できます。
メソッド戻り値
Javaオブジェクトを返却するだけで大丈夫です。フレームワークが自動でJSONへパースしてくれるので特に操作は必要ありません。
ステップ3
アプリケーションの設定ファイルを変更します。プロジェクト直下にあるpom.xmlを編集します。
・pom.xml
YOUR_PROJECT_ID.appspot.com
YOUR_PROJECT_IDを自身のGCPプロジェクトIDに変更して保存してください。
コードは以上です。
アプリケーションの確認
それでは作ったアプリケーションの動作を確認していきましょう。
5つのステップで確認します。
ステップ1: アプリケーションのビルド
ステップ2: APIドキュメントの生成
ステップ3: Web API のデプロイ
ステップ4: Webアプリケーションのデプロイ
ステップ5: 動作確認
自分が書いたコードが想定した通り動作するかの検証します。
ステップ1
まずは、プロジェクトのビルドを行います。
アプリケーションのRootフォルダで以下のコマンドを実行します。
$ mvn clean package
BUILD SUCCESSメッセージが表示されたら成功です。
[INFO] ------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------
[INFO] Total time: 16.486 s
[INFO] Finished at: 2019-05-23T16:52:00+09:00
[INFO] ------------------------------------------
ステップ2
次にOpen APIの構成ファイルを生成します。
以下のコマンドを実行して、openapi.json という名前の OpenAPI ドキュメントを生成します。
$ mvn endpoints-framework:openApiDocs
こちらも先ほどと同じようなBUILD SUCCESSメッセージが表示されれば成功です。
target/openapi-docs/openapi.json が生成されていることを確認してください。
Open APIとは
REST API を定義するための定められた業界標準の仕様です。
ステップ3
前のステップで生成した OpenAPI 構成ファイルをデプロイします。
$ gcloud endpoints services deploy target/openapi-docs/openapi.json
これにより、新しい Endpoints サービスが作成され、YOUR_PROJECT_ID.appspot.com という形式の名前が付けられます。正常に完了すると、サービス構成 ID とサービス名を示す次のような行が表示されます。
Service Configuration [2019-05-24r0] uploaded for service [ca-sano-test.appspot.com]
ステップ4
いよいよGCP環境にアプリケーションをデプロイします。
$ mvn clean appengine:deploy
しばらく待ち、次のうようなメッセージが表示されれば成功です。
[INFO] GCLOUD: Deployed service [default] to [https://ca-sano-test.appspot.com]
ローカル環境で動かす
今回はGCP環境へデプロイしましたが、実際の開発時にはロカール環境で動作確認しながらの開発になるかと思います。以下のコマンドでローカル環境で起動できます。
$ mvn clean appengine:run
ステップ5
最後のステップとしてアプリケーションにリクエストを投げてみしょう。
YOUR_PROJECT_IDは自身のプロジェクトIDに変更してください。
$ curl https://YOUR_PROJECT_ID.appspot.com/_ah/api/hello/Taro
注)/_ah/api/がURIに含まれていますが、これはフレームワークがデフォルトで設定してるbasePathです。
次のようなレスポンスが帰って来れば成功です。
{
"message": "Welcome! Taro"
}
ドキュメントは自動生成でメンテナンスする
ここまでコードを書いて動作を確認してきました。
チーム開発をしている場合、作ったWeb API をフロント開発者などに共有する必要があるかと思います。
もし、手書きのドキュメントを書いていたら、コードの変更のたびに開発者が手で編集が必要になります。コードがそのままドキュメントにるのが理想です。
実はこれまでの工程で、自動ドキュメント生成の準備は整っています。
ドキュメントを確認してみましょう。
デベロッパーポータルで確認する
GCPコンソールのメニューから[エンドポイント] → [デベロッパー ポータル]を開きます。
5〜10分かかるのでお茶でも飲みながら待ちましょう。
作成できました。
URLをクリックして作成されたデベロッパーポータルを確認しましょう。
途中、アクセス認証のステップがあると思います。
デベロッパーポータルのトップページが確認できたらサービス名(YOUR-PROJECT-ID.appspot.com)をクリックして開いてみましょう。
見ることができましたね。
これで作ったWebAPIをチームで共有することができ、メンテナスフリーでドキュメント化も可能になります。
まとめ
App EngineでWeb APIを作る方法を解説してきました。
煩わしいコードを書かずに簡単にWebAPIを作ることができたのではないでしょうか。
今回は単純なAPIでしたがEndpoints Frameworkでは認証やアクセス制御もできます。
デベロッパーポータルを使えばドキュメントがメンテナンスフリーになるのでチーム開発に是非役立ててください。
それでは、よきWeb API開発ライフを!