ども、@kimihom です。
私は仕事がら、外部の API を利用することがたくさんある。そこで利用しているツールやコツなどをご紹介する。
Postman
Postman は HTTP リクエストを手動で簡単に組み立てて実行し、レスポンスを表示してくれる Chrome アドオンだ。
一般的に外部に公開されている API のほとんどは RESTful な形式となっており、フォームや URL で実現できる GET, POST 以外の PUT や DELETE といった HTTP メソッドを実行できなければならない。そこでいくつか手段はあるんだけども、Postman が一番簡単に構築できて、リクエストの履歴も管理してくれるので便利だ。
API の POST でどんな形式でデータを送るのかって所でまたサービスごとに異なる部分が多かったりする。 HTML でフォームを送るのと同じように form-data で送るのか、URL エンコードされた状態の x-www-form-urlencoded, はたまた JSON 形式で送るといった場合もある。Postman ではこれら全部に対応しており、各社提供する API ごとの差分をうまく吸収してくれる。
API の利用は、いきなりコードから書かないということが大事だ。まずは Postman でパラメータを組み立ててリクエストを送って実行してみるところから始める。そこで理想的なレスポンスが得られるようになって初めて、開発を始めるとスムーズに連携が実装できる。
Request Bin
OAuth で認証する Web サービスを使う場合、何かしら POST リクエストを受け取れるようなサーバーを用意しなければならない。最初からわざわざそのための環境を用意するのは面倒だし調査目的の場合に時間がかかるというデメリットがある。
そこで一時的に Webhook の受け取り先として Request Bin は重宝する。
ここで発行された URL を OAuth のリダイレクト URI に指定して、どのようなトークンが渡ってくるのかを実験することができる。Request Bin は基本的な Webhook 周りのテストにおいてあらゆるケースで便利になることが多いので、一度使ってみていただけたらその便利さがわかると思う。
OAuth 実装のコツ
OAuth の連携の実装は骨の折れる作業だ。サービスとの連携が完了した後、定期的にそのAPIを呼ぶためにアクセストークンとリフレッシュトークンの２つをうまく管理しなければならない。
特にOAuth連携を運用すると、連続で呼ぶAPIリクエストの途中でアクセストークンの期限が失効するケースが往々にして起こる。１時間に1回定期的にAPIを呼ぶような仕組みにしている場合、アクセストークンの有効期限が3時間の時には3回の実行のうち1回絶妙なタイミングでのトークンの期限の失効が発生するである。
リフレッシュトークンを使ってアクセストークンを更新する実装は以下の２パターンある。
- リクエストの度にレスポンスコードをチェックし、アクセストークンが無効になってたら更新する。(この場合、再送する仕組みを実装する必要あり)
- 一連のAPIリクエストの最初の１回目で必ずアクセストークンを更新する
１つ目の方法がセオリーではあるが、２つ目の方法の方が実装はしやすい。APIアクセスの頻度が多ければ前者を、少ない場合は後者をという使い分けができるだろう。
これらの管理はもしかすると第三者の提供する APIクライアントがうまく実装しているケースもある。実装が手間だと感じたら専用のAPIクライアントを利用することも検討しよう。私の場合は公式のAPIドキュメントを読んで生のHTTPリクエストを送った方が早く実装できるので、自前でリクエストを送るようにしている。
終わりに
特にビジネスの現場においては、他のビジネス向けツールとの連携は特に需要の高い機能となってくる。そうするとこれらAPI連携の実装は必ず必要になってくるはずだ。
色々な外部のAPIを触って実装してみると、良いAPI、悪いAPIが何なのかがわかってくる。その理解によって、例えば自社でAPIを実装する時にも設計の大きな参考になることだろう。
