デベロッパーポータル提供終了
Cloud Endpoints にAPIドキュメントをデプロイするとデベロッパーポータルも自動生成されてものすごく便利！ と思っていたのですが、非常に残念なことに提供終了となります。
Cloud Endpoints Portal の「デベロッパーポータル」
スタートガイドにリファレンス、APIキーをセットしてここでテストしたりもできます。
自社開発のアプリを API 化する際にいくつかの選択肢から Cloud Endpoints に決めたのには、この便利なデベロッパーポータルの存在も大きかったです。
Cloud Endpoints Portal は非推奨となりました。2023年3月21日以降は使用できません。
これをみて、自社API に Cloud Endpoints を利用していた方々はガッカリしたかもしれません。そして、どんな対応が必要なのか、Cloud Endpoints をこのまま使い続けて良いのか、乗り換えた方がいいのか、色々と疑問・不安が出てきたかもしれません。
私も担当者として色々と調査したのですが、あまり情報が出ていなくて苦労したことも多かったのでここで共有したいと思います。
デベロッパーポータル提供終了で、自社のAPI提供に影響はある？
結論から言うと、影響はありません。
APIの実体は、バックエンドアプリとEndpointsにデプロイする APIドキュメント（YAMLファイル）で構成されています。
デベロッパーポータルは、APIの仕様（パラメータ、レスポンスの形式や例など）を外部に伝えるためのモックサーバです。
デベロッパーポータル提供終了に向けてやること（追加費用なし）
Cloud Endpoints にYAMLファイルをデプロイするたびに API仕様書を書き直す事態を避けたいなら、やはりデベロッパーポータルの代替となるモックサーバが必要になります。
代わりのモックサーバを作るなら、Swagger UI が最も簡単です。新しく何かを作る必要がないからです。しかも無料。
過去の記事で紹介したように、Swagger Editer で既存のAPIドキュメント（YAMLファイル）から自動生成したサーバーファイルを AppEngine にデプロイすれば、代わりのモックサーバを簡単に立てることができます。
よほど特殊な事情でもない限りは App Engine の無料枠に収まるので、これも無料です。
Swagger Editerから自動生成してApp Engine にデプロイしたモックサーバ
APIキーをセットしてテストすることもできます。
もし将来的に完全に自動化したければ、Cloud Build と連携させて CI/CD パイプラインを作ることも可能です。
代わりの画面はいらない場合
APIのバージョン変更に伴い、仕様書もいちいち書き換えて利用者に連絡せねばならず、管理コストがかかります。が、もう画面はいらないなら、最もシンプルな方法は、エクセルやワードでAPI仕様書を書いてお客様に送ることです。Cloud Endpoints を使っていても API 自体には何も影響がないので、API の仕様を伝えられれば良いわけです。
あるいは、reDoc のようなサービスを使い、APIドキュメントを html ファイルとして出力することもできます。自分で仕様書を書き起こす手間は省けます。
試しに作ってみたらこんな感じでした。
reDoc で自動生成したHTMLファイル
色？というかテイストはなんとなくデベロッパーポータルと似てますね。ただのHTMLなのでテストはできませんが、ワードの仕様書よりは見やすいのでこれをメールで添付してもいいかもしれません。
その他の疑問と回答
- デベロッパーポータルは誰が使う？
- 基本的にはお客さん（のエンジニア）が使います。
- エラー時のレスポンスを修正できる？
- できます。APIの仕様なので、 Cloud Endpoints もしくはバックエンド側で制御するため、デベロッパーポータルや代わりのモックサーバは関係ありません。
まとめ
- デベロッパーポータル提供終了でも、Cloud Endpoints のAPIそのものに影響はない
- デベロッパーポータルの代わりのモックサーバは、Swagger ＋ App Engine で無料・簡単に作れる
- reDoc のように APIドキュメントからHTMLファイルを自動生成するサービスもある