ボクココ

個人開発に関するテックブログ

API 開発において認証以外で気をつけるべきこと

ども、@kimihomです。

前回の 認証を含む API 開発で検討すべきこと は多くの方にお読みいただき、API の関心の高さを伺えた。

さて、今回は認証以外でAPI開発において考慮すべきこととして以下の課題について考えてみる。

  • アクセス制御(認可)
  • 不正アクセスの制御
  • バージョン管理の課題
  • ドキュメント作成の課題

アクセス制御(認可)

まずは認可について。トークンによってユーザーは識別できたけども、そのユーザーができること・できないことができるようになったわけではない。基本的に認可の話はプログラム側でユーザーと役割を定義してできることできないことをゴリゴリ書いていくだけだが、より一般的な方法がある。

それは前回の認証コードを発行する"アプリケーション" ごとに権限を付与する方法である。ここでアプリケーション(アプリ)という概念が出てきたので少し解説しよう。

API の世界で出てくる"アプリ"とは外部の開発者がAPI認証をしたい時に作成する自分用のスペースと言える。Twitterアプリを作ったことがある方なら分かる通り、それぞれ"アプリ"を作ることで専用の cleint_id, client_secret を手に入れる。その情報とリダイレクトURLを指定することで、あのよくあるTwitterログイン画面が出てくる。図で表すと以下のようなイメージ。

f:id:cevid_cpp:20151223001257p:plain

このアプリに例えば読み込み専用だとか、管理者用だとかでアプリをそれぞれ作成することで、権限を分離することができる。よくあるAPIにはこうしたアプリごとに権限を持てるものが多い。また、アプリという単位でAPIを使わせることで、不正な使い方をしているアプリだけ停止させたり、アプリごとに使用状況を把握できるなどのメリットがある。

注意していただきたいのが、"スマホアプリ"などの概念とは違うものなので混同しないように。俗に言う"Facebookアプリ"とは、あれは単なるFacebook内でiframeで埋め込めるスペースだけのものである。今回のAPIで出てくるアプリと勘違いしやすいところである。APIのアプリの概念を全くイメージがつかない方は、Twitter連携アプリを作成してみることをお勧めする。

不正アクセスの制御、アクセス解析

さて私達がWebアプリケーションを開発するときは、定番のGoogle Analyticsをはじめとしたツールを利用することだろう。APIも同様にどんなクライアントがどの APIをどのくらい利用しているのか、理解しておきたいところだ。それがわかれば、不正アクセスをしているクライアントを把握することにもつながり、安全にAPIを運用することができるようになる。

さてと Google AnalyticsのAPIバージョンを探そうにも、そういうのが見当たりない。当たり前のことだが、これはWebアプリではないので、JavaScriptで別サーバーにデータを飛ばすみたいなことは不可能である。そのためほとんどのAPIを提供する会社は自前で実装する必要が出てくる。

これをなんとかできないだろうか。

最近になって一つソリューションが登場した。それが本ブログでも度々紹介する Amazon API Gateway である。この API を一種のプロキシーみたいな感じで間に挟ませることでアクセス解析が可能になる。

クライアント  <->  Amazon API Gateway < -> API サーバー

実際に運用するところまでは私もまだ検証段階であるため、詳しくは書くことはできないがドキュメントを読む限り解決が可能そうだ。

バージョン管理

API 開発で面倒だけど考えなければならない点が"バージョン管理"である。これもWebアプリとの比較してみよう。 Webアプリであれば修正があればそのままサーバーに配置して更新すれば良いだけである。ユーザーがサービスと通信するのはブラウザを経由してだけなので、利用するユーザーはソースが常に最新の状態に保つことができる。

しかしAPIではそうはいかない。例えば念願のアプリver1をリリースしたとしよう。そのアプリの向き先は常に一つのAPIだけである。そこで、例えばAPIのレスポンスが変わった ver2をリリースしたいとする。その時、 ver1を使い続けるユーザーが出てくる ため、APIを同じURLでver2用でそのままリリースしてしまうと、ver1ユーザーはアプリを使えなくなってしまうリスクが生じる。

これを回避するために、APIを変更、削除するようなことがあれば API のバージョンを区切ってどんなアプリでも利用し続けられるようにしなければなrない。実際のところこの実装はよく考えないと面倒で、多くの重複が発生する。バージョン管理は各種API作成のフレームワークなどを利用してうまく管理するしかない。RailsでのAPIバージョン管理についてはまた今度の記事で。

ドキュメント生成の課題

さて、APIを頑張って書きました。そしてたくさんの人にこのAPIを使って欲しい!となった時、開発者は何を見て開発するか?ドキュメントはAPIにおけるHTMLのようなもので、これがなければ公開APIの意味がなくなってしまう。もちろん社内専用APIとかでもドキュメントがないとチーム間で開発ができない。

じゃあと言ってAPIを開発した人が普通にWikiなどにドキュメントを書くとする。書かないよりはマシだが、必ず更新の問題が発生する。APIを変えたら必ずAPIのドキュメントも修正しなければならない。しかもバージョンごとに。これは気の折れる作業である。

てことでAPIドキュメント生成を自動化したい。そうすればAPI開発に集中でき、ドキュメントは常に最新であることが保証できる。

Railsであればソース中に書いたドキュメントがSwagger形式で吐き出されるGemなどがある。これも次の回で紹介する。その他の言語でもきっとSwagger対応のAPI作成フレームワークがあると思うので調べていただければと思う。

Swagger とは "API用 のインタフェース" だ。作ったAPIがどういう作りなのかを定義した専用のjsonを用意すれば、最適化されたドキュメントの生成と、実際にAPIをテストすることのできるUIを作成してくれる。

f:id:cevid_cpp:20151223004122p:plain

この Swagger が、前述した Amazon API Gateway と非常に親和性が高い。 Swagger 形式で出力できれば、その形式を Amazon API Gateway がインポートすることで、Amazon API Gateway 側で必要だったAPIの設定が不要になる。今後、 Rest の標準化団体もこのSwaggerをベースとして展開していくそうで、 API といえば Swagger という認識を持ってもらっていいと思う。

Amazon API Gateway のその他の利点

Amazon API Gateway を挟めば、以下の点でメリットが生まれる。公式引用

API Gateway により開発者は、認証とアクセスコントロール、トラフィック管理、モニタリングと分析、バージョン管理、およびソフトウェア開発キット(SDK)生成を処理するインフラストラクチャを開発および維持することなしに、バックエンドサービス向けの API を作成および操作できます。

バックエンドAPI開発で抱える共通の課題を解決してくれるし、しかも利用は安いのでどんどん利用しよう。

終わりに

今回は 認証以外で API 開発において頭を悩ますトピックと、それに対応するための技術を紹介した。こういうのはあらかじめ知って設計しておかないと後になって替えのきかない話になってしまうので、API開発の際は必ず考慮するようにしたいところだ。

さて、次回からいよいよ Rails コーディングの話に移っていきたいと思う。ここから先は私も検証しながらになるので記事になるには時間がかかるかもしれないが気長にお待ちいただければ幸いである。