みなさんこんにちは。teratail開発チームの出川です。

APIとはApplication Programming Interfaceの略で、Web APIはHTTPを通じてアプリケーションを扱うことができるインターフェースです。世の中のWebサービスには、そのAPIを公開しているものが多々あります。Web APIが公開されていると、他のソフトウェアから二次的にそのWebサービスを利用することができます。

Web APIを公開しているサービスは次々と増えています。teratailもユーザが自由に使えるWeb APIを公開していて、サイト内の質問や回答の情報を二次利用することができます。

teratail API ｜teratail（テラテイル）

https://teratail.com/api

参考：teratail-archive

http://argius.net/teratail-archive/

MicrosoftやDocomoなど、企業で積極的にWebAPIを公開している例もあります。またスマートフォンアプリではサーバとの通信のためにWeb APIを利用することが多く、これからますますWeb APIを利用することは重要になっていくでしょう。

Web APIは他のサービスで使われているものを二次利用する性質上、その使い方には少しコツがあります。今回はWeb APIを利用するにあたっての基礎知識をまとめていきたいと思います。

HTTPの仕組み

Web APIのほとんどはHTTPによって通信を行います。そのため、HTTPの仕組みや仕様を理解しておくことはとても重要です。

HTTPはWebサーバとWebブラウザがデータをやりとりするのに使われるプロトコルです。Webサイトの場合のレスポンスは主にHTMLであり、Webブラウザがそれを描画して人間の目に見えるようにするのに対して、Web APIのレスポンスはJSONやXMLといったソフトウェアが扱いやすい構造になっています。

Web APIへのリクエストにはURIとメソッドの2つを指定する必要があります。Web APIではURIのことをエンドポイントとも呼びます。

メソッドにはGET, POST, PUT, DELETE, HEAD, OPTIONSなどがあります。GETはリソースを取得する時に用い、POSTはリソースの作成、PUTはリソースの変更、DELETEはリソースの削除など、その役割が分かれています。

各種Web APIのドキュメントはこれらHTTPの仕様を大前提としているので、基礎は必ず頭に入れておく必要があります。

より詳しい知識はRFCにまとまっていますので、興味のある方は見てみるとよいと思います。

参考：HTTP/1.1 — RFC 7230～7235 — 日本語訳

http://www.hcn.zaq.ne.jp/___/WEB/RFC723X-ja.html

Web APIの試し方

Web APIを発見したら、それらを手元で試してみるのが仕様や挙動を理解するのに便利です。もちろん、HTTPの仕様の基礎を理解していることが必要です。

まずそもそもWeb APIを利用する際には、認証を行う必要があるものもあります。その際はアクセストークンという文字列を取得し、それをリクエストに含めて利用することが多いです。たとえば、Twitter APIを利用するためにはアプリケーション登録を行って、Consumer Key（API Key）とConsumer Secret（API Secret）を取得する必要があります。

Web APIの動作を試すのにもっとも汎用的に利用できるのがcurlコマンドです。curlはUNIX系のOSであればほとんどの場合デフォルトでインストールされていますし、オプションにより詳細な通信が可能です。

$ curl -X GET https://teratail.com/api/v1/questions?limit=3 | jq .
{
  "meta": {
    "message": "success",
    "total_page": 15542,
    "page": 1,
    "limit": 2,
    "hit_num": 31083
  },
  "questions": [
    {
      "id": 31445,
      "title": "インスタンスの生成について",
      "created": "2016-04-04 17:16:04",
      "modified": "2016-04-04 17:16:04",
      "count_reply": 0,
      "count_clip": 0,
      "count_pv": 2,
      "is_beginner": false,
      "is_accepted": false,
      "is_presentation": false,
      "tags": [
        "Swift",
        "Swift 2"
      ],
      "user": {
        "display_name": "14ic158p",
        "photo": "https://cdn.teratail.com/uploads/avatars/34165/NBBp0Sd9_thumbnail.jpg",
        "score": 17
      }
    },
    ... (略)
  ]
}

MacではCocoaRestClientというツールがあり、GUIでWeb APIへのリクエストをすることが可能です。JSONの整形やリクエストの保存なども可能なので、試すには非常にオススメのツールです。

また単純にレスポンスとして返ってきたJSONの整形や抽出を行う場合は、jqというツールが便利です。

もちろんこれらのツールを使わなくても、自分の使い慣れた言語で触ることもできます。自分に合ったツールを使って試してみてください。

参考：オススメのモックWEBサーバー構築方法を教えてください。

https://teratail.com/questions/27066

レートリミットを意識する

多くの公開Web APIには、時間あたりに使用できる回数が決まっています。これをWeb APIではしばしばレートリミットと呼びます。IPアドレス単位やリソース単位で制限を行っていることも多く、GTmetrixのWeb APIなど特定の行為をするとクレジットが増えたりするものもあります。アクセストークンを利用することでレートリミットが緩和されるものもあり、その形態はさまざまです。

まず利用する際には、この制限回数がどれほどかを把握しておくことが必要です。

レートリミットを超えるアクセスは正しいレスポンスを返さないので、サービスが利用できない旨をユーザに伝え、これ以上リクエストを送らないようにする必要があります。レートリミットを超えてもリクエストを続けるとDoS攻撃とみなされてしまうこともあるので注意が必要です。

アプリケーションから不用意にWeb APIにリクエストさせず、Web APIからのレスポンスをキャッシュしてリクエスト回数を減らすのがもっとも基本的な対策方針になります。

処理の書き方

アプリケーションでWeb APIを利用したコードを書くときは、通常とは違った注意が必要です。基本的にWeb APIは他のサービスを利用するので、レスポンスが届くまでには時間がかかります。このため待っている間のユーザのストレスを軽減する仕組みが必要です。

Webアプリケーションでは、サーバサイドからのWeb APIへのリクエストはなるべく避けるべきです。Web APIからのレスポンスを待つ時間が全てユーザの待ち時間となってしまうためです。

サーバサイドからリクエストをする場合は非同期通信にするか、キャッシュを用いて2回目以降のリクエストを減らすなどの工夫が必要です。非同期通信に関しては、JavaScriptであればXMLHttpRequrest、Go言語であればnet/httpパッケージを利用するなど、簡単に実現が可能な言語も多いといえます。

参考：swift2でHTTP通信を行う方法｜teratail

https://teratail.com/questions/30313

WebアプリケーションのフロントエンドからJavaScriptで非同期通信を行うことはよく行われます。認証に必要な情報をユーザに送るのは、トークンが盗まれる可能性があり非常に危険なため、認証の必要ないWeb APIのみを扱うことになります。

SSL（https）でリクエストしたページからは、SSLなし（http）のWeb APIへのリクエストは安全でないリクエストとしてブラウザがブロックしてしまうので利用できません。アプリケーションの通信をHTTPSで行っている場合はあらかじめ確認しておきましょう。

Web APIを多用するスマートフォンアプリでは無線の通信状態によってアプリケーションそのものの処理時間が大きく変わります。Web APIのレスポンスを待ってユーザに情報を表示させるときはプログレスバーを表示したり、処理をバックグラウンドに回してユーザが操作不能な時間を減らすのが効果的です。

先に挙げたレートリミットでWeb APIが利用できない場合や、Web APIがダウンしている場合なども想定する必要があります。もしWeb APIが利用できずアプリケーションが正しい動作ができない場合には、その旨をユーザに伝える必要があるかもしれません。

おわりに

ここまで、Web APIを利用するにあたっての基礎知識や、処理を実装する際に注意する点をまとめてきました。

利用に関しては、よくそのWeb APIのドキュメントを読むようにしましょう。障害やメンテナンスによって使えない時間帯が発生したり、機能追加や削除によって利用しているアプリケーションのコードを変える必要が出てくる場合もあります。

Web APIで他のWebサービスのデータや機能を二次利用することで、自分のプロダクトをよりよいものにすることができます。公開Web APIという巨人の肩の上に乗って、今までになかった価値を生み出すアプリケーションを作っていきましょう。

teratail【テラテイル】｜思考するエンジニアのためのQAプラットフォーム

https://teratail.com/