前回の記事で、APIの基本について触れました。今回は、開発者向けに実用的な内容を紹介します。
Google Cloud を使った API 自社開発
APIを公開する方法は色々考えられますが、今回は Google Cloud の Endpoints を使った場合をご紹介します。
＜使うもの、役割＞
- Cloud Functions（第二世代）もしくは Cloud Run
- バックエンドアプリ、サービス、API として外部に提供する機能
- Swagger Editer
- API ドキュメント を書くためのエディタ
- 「Generate Server」で サーバファイルを出力
- Cloud Endpoints
- API を公開、保護、モニター、分析したり、割り当てを設定したりする
- App Engine
- APIドキュメントを使った モックサーバ
＜自社 API 開発手順＞
- Cloud Run にサービスを作成する
- Open API 構成ファイル（YAML） を作成する
- Cloud Endpoints にAPI ドキュメント（YAML）をデプロイする
- App Engine にモックサーバをデプロイする（デベロッパーポータル非推奨の対応）
API ドキュメント（YAML） を作成する
Swagger Editer（https://swagger.io/tools/swagger-editor/）を使います。 ブラウザ上で動作するエディタで、左がYAMLファイル、右がプレビューです。編集しながら生成されるドキュメントを確認できてありがたい。
作成が終わったら、[File] の [Save as YAML] を選択するしてYAMLファイルをダウンロードします。
Cloud Endpoints に API ドキュメント（YAML）をデプロイする
先ほど作成したYAMLファイルを、Cloud Endpoints にデプロイします。
Cloud Endpoints が Swagger に完全に対応しているわけではないので、少し文法が違ったりエラーが出たりすることもありましたが、基本的にはEndpoints のクイックスタートの通りで問題ありません。
https://cloud.google.com/endpoints/docs/openapi/set-up-cloud-run-espv2?hl=ja
構成はこんな感じになります。
App Engine にモックサーバをデプロイする（デベロッパーポータルの代わり）
2023 年 3 月 21 日以降 Cloud Endpoints Portal（デベロッパーポータル）は利用できなくなりますが、現時点では Endpoints にデプロイが完了するとデベロッパーポータルが自動的に作成されます。
デベロッパーポータル（例）
なお、Cloud Endpoints Portal（デベロッパーポータル）が終了するだけで、Endpoints 自体は影響を受けないので、ご安心を。
今回は、デベロッパーポータルの代わりに、Swagger Editer で自動生成されるサーバーファイルを App Engine にデプロイして代替のモックサーバとします。 まずは、Swagger Editerの [Generate Server] で [nodejs-server] を選択します。すると、モックサーバファイル一式がダウンロードされます。
次に、ダウンロードしたファイル一式を、ローカルPCのターミナルで、gcloud CLI を使用して App Engine スタンダード環境にデプロイします。
手順は App Engine のクイックスタートの通りで問題ありません。
https://cloud.google.com/appengine/docs/standard/nodejs/building-app/deploying-web-service?hl=ja
デプロイできたら、Google Cloud コンソールで App Engine サービスを表示します。
default という名前のサービスが 1 つ表示されます。このデフォルトのサービスは、次の URL で公開されています。
https://PROJECT_ID.REGION_ID.r.appspot.com
Swaggerのモックサーバは末尾に /docs/ をつけると表示されます。これで、モックサーバがWeb上に無事公開されました。
ちなみに、弊社サービスの「ソトミル.イベントAPI」のモックサーバは以下のような見た目になっています。
実際にお客様に使っていただくときは、こちらのモックサーバのURLに加えて、個別で作成したAPIキーをお渡しします。
APIキーごとに制限をかけたり、モニタリングしたりしているのですが、その辺の仕組みも機会があれば別の記事でご紹介したいと思います。
まとめ
- Cloud Endpoints を使えば安く、簡単に、自社サービスを API化できる
- Swagger Editer で APIドキュメント、モックサーバが作成できる
- デベロッパーポータルが終了するので代わりのモックサーバが必要
関連記事
デベロッパーポータル終了のお知らせ
https://cloud.google.com/endpoints/docs/deprecations/endpoints-portal-deprecation?hl=ja