Web API入門 第1回 APIの概要とデータの取得
サービスのデータやプログラムを外部から利用できるWeb APIの使い方を解説していきます。まずはWeb APIの役割を理解し、データを取得してみましょう。
Web APIとは？
API（Application Programming Interface）とは、サービスのデータを外部のアプリケーションやプログラムから扱うための機能を提供するインターフェースです。中でも、HTTP通信によってやりとりを行うAPIをWeb APIといいます。
Twitter APIを利用して独自のTwitterクライアントを作ったり、Amazon APIを利用して自分のサイトに最新の商品情報を掲載したりできるのは、TwitterやAmazonが、自社のデータを扱うための処理を抽象化したプログラム（API）を外部に向けて公開しているためです。
このように、公開されているWeb APIを利用することで、サービスから取得したデータを加工したり、複数のAPIを組み合わせたりして、新たなサービスを開発することができるようになります。
まずは、Web APIの概要を理解しましょう。その上で、今回はGitHub APIを例に、実際にWeb APIを利用してみます。
Web APIの探し方
Web APIにはさまざまな種類があり、一般公開されているAPIの一覧を見ることができるまとめサイトなどもあります。また、特定のWebサービスのAPIを探す場合は、Google検索を利用するとよいでしょう。たとえば、GitHubのAPIを探すには『GitHub API』と検索すると、検索結果の一番目に公式ドキュメントが表示されます。
APIが提供されていない場合は、スクレイピングなどで無理やりデータを取得するしかありませんが、Webサービス側のHTMLの変更によって容易に破綻したり、不正なアクセスとしてBANされてしまう可能性もあります。そのため、利用はおすすめできません。
Web APIの役割
Web APIを利用することで、サービスが持つデータを外部からでも利用できるようになると述べましたが、具体的にはWeb APIはどのような役割を果たしているのでしょうか。
たとえば、サービスのデータをWeb APIで提供するような場合において、外部のプログラム*とサービスのデータベースの中間に位置して、やりとりの仲介を行うのがWeb APIです。外部のプログラムからサービスのデータベースに直接アクセスすることはできませんが、Web APIが橋渡しをすることで、外部のプログラムがサーバー上にあるデータを取得したり、サーバー上のデータを更新したりできるようになります。
*注：外部のプログラム
サービス内のプログラムであっても、ブラウザ（JavaScript）やネイティブアプリなどからのHTTP通信によるアクセスでは、サーバー上のデータに直接アクセスできません。そのため、ここでいう「外部のプログラム」にはこれらも含まれます。
両者を仲介するWeb APIは、外部のプログラムからの命令が、Web APIで提供している機能と一致しない場合には受け付けてくれません。また、公開範囲が限られているWeb APIの場合は、対象範囲でなければ利用を許可しません。
つまり、Web APIを利用する側は、Web APIが提供している機能を利用する以外のことはできないということです。そのため、サービスのデータを勝手に書き換えたりはできませんし、取得できるデータもサービスが持つすべてのデータが取得できるわけではなく、Web APIで公開しているデータだけが対象となります。
Web APIが提供する機能しか利用できない代わりに、内部の構成や実装を一切知らなくても、必要事項をWeb APIに投げるだけで、欲しいデータを得ることができるのです。
どのような機能が提供されているかはWeb APIによって異なるため、APIのドキュメントを読む必要があります。外部から利用されることを前提としているWeb APIであれば、APIを利用するにあたっての必要な情報はすべてドキュメントに記載されています。
Web APIを扱うための環境を用意
Web APIの概要については、なんとなくイメージが湧いたのではないでしょうか。それでは、習うより慣れろということで、さっそくWeb APIを利用してみましょう。
Web APIは普通のWebサイトへのアクセスと同じように、HTTPプロトコル*を利用し、リクエストとレスポンスによってやりとりを行います。よって、HTTP通信が可能な環境であれば、ブラウザに限らずどのような環境からもWeb APIにアクセスが可能です。
*注：HTTPプロトコル
HTTPプロトコルによるクライアントとサーバー間のやりとりの仕組みについては、こわくないAjax - 第1回 HTTPの仕組みにて詳しく解説しています。
手軽に試すなら、ターミナルからcurlコマンド（HTTP通信を行うコマンド）を利用する方法が早いのですが、ここでは、フロントエンド・エンジニアが普段から使い慣れているブラウザからのAjax通信でWeb APIを利用してみましょう。
生のXHRをそのまま扱うとコードが長くなり面倒なので、axios*を利用します。次のようなHTMLファイルを作成し、同じディレクトリに空のapp.jsを作成したら準備は完了です。
index.html
<!DOCTYPE html>
<html lang="ja">
<head>
<meta charset="utf-8">
</head>
<body>
<script src="https://unpkg.com/axios/dist/axios.min.js"></script>
<script src="app.js"></script>
</body>
</html>*注：axios
axiosはHTTPリクエストを行うためのライブラリです。XHRをラップしたAPIで構成されているので、シンプルに記述することができます。詳しくはおすすめライブラリつまみ食い - 第10回 axiosにて解説しています。
GitHub APIを利用するための準備
この記事では、GitHub API（REST API v3）を利用していきます。APIの使い方はすべて公式ドキュメントに掲載されているため、こちらを参照します。
ドキュメントの右カラムは、利用できるAPIの種類の一覧です。一番上のOverviewはAPIを構成する基本事項などが記載されています。
ルートエンドポイントを設定する
APIを利用するには、アクセス先のURIが必要で、URIはリソース（参照に値するデータの塊）ごとに1つ（またはそれ以上）割り振られています。
たとえば、特定ユーザーの情報はhttps://api.github.com/users/:username、特定ユーザーのリポジトリ一覧はhttps://api.github.com//users/:username/reposにアクセスすることでデータを取得できます。このように、リソースごとに割り振られたURIのことをエンドポイントといいます。
ドキュメントに記載されるエンドポイントは、/users/:usernameのようにルートパスになっていることが多く、また、APIのルートエンドポイントであるhttps://api.github.com部分は省略できたほうがコードの見通しもよくなります。
個別のリソースへのアクセス時にルートパスで指定できるように、axiosのbaseURLにルートエンドポイントを設定しておきます。
app.js
const request = axios.create({
baseURL: 'https://api.github.com'
})GitHub APIからパブリックな情報を取得する
準備が終わったので、さっそく実際にAPIを叩いて、自分のアカウントの情報を取得してみましょう。
ドキュメントを参照する
ユーザー情報のAPIにアクセスするための情報は、Users | GitHub Developer Guideに記載があります。このうち、Get a single userが個別のユーザーの情報を取得するAPIです。
ドキュメントの見方について軽く触れておきます。
見出しのすぐ下には、利用するHTTPメソッドとアクセス先のエンドポイントが記載されています。
GET /users/:usernameこの例の場合は、GETメソッドを用いて/users/:usernameにアクセスすると、データが取得できるということです。
その下の「Response」は、APIから返ってくるレスポンスのフォーマットです。GitHub APIはJSON形式でレスポンスが返ってきます。
HTTPメソッドの種類
APIの操作を行うHTTPメソッドには、よく使われる主なものに次のような種類があります。それぞれのHTTPメソッドについては、次回以降で詳しく解説します。
GET: リソースの取得POST: リソースの作成PUT: リソースの作成、リソースの更新PATCH: リソースの部分更新DELETE: リソースの削除HEAD: リソースのメタデータの取得OPTIONS: リソースがサポートするメソッドを調べる
自分のアカウントの情報を取得する
APIへのリクエストに必要な情報（HTTPメソッドとエンドポイント）をドキュメントから得られたので、app.jsに次のように記載します。
app.js
const request = axios.create({
baseURL: 'https://api.github.com'
})
request.get('/users/***') // ***部分を自分のアカウント名に置き換える
.then(res => res.data)
.then(console.log)ここで追加した箇所を、1行ずつ分けて見ていきましょう。
request.get('/users/***')/users/:usernameにGETメソッドでリクエストを行います。
.then(res => res.data)APIから返されるレスポンスには、実データ以外にもステータスなどのさまざまな情報が含まれています。GitHub APIの場合は、レスポンスのdataオブジェクトに実データが入る仕様になっているため、res.dataをPromiseで返すことにより、次の.thenに実データだけを渡します。
.then(console.log)渡されたデータをブラウザのコンソールに表示します。
index.htmlをブラウザで開いて、コンソールに次のようなデータが表示されていたら成功です。
{
"login": "***",
"id": ******,
"avatar_url": "https://avatars3.githubusercontent.com/u/******?v=4",
"gravatar_id": "",
"url": "https://api.github.com/users/***",
"html_url": "https://github.com/***",
"followers_url": "https://api.github.com/users/***/followers",
"following_url": "https://api.github.com/users/***/following{/other_user}",
"gists_url": "https://api.github.com/users/***/gists{/gist_id}",
"starred_url": "https://api.github.com/users/***/starred{/owner}{/repo}",
"subscriptions_url": "https://api.github.com/users/***/subscriptions",
"organizations_url": "https://api.github.com/users/***/orgs",
"repos_url": "https://api.github.com/users/***/repos",
"events_url": "https://api.github.com/users/***/events{/privacy}",
"received_events_url": "https://api.github.com/users/***/received_events",
"type": "User",
"site_admin": false,
"name": "***",
"company": "@pxgrid ",
"blog": "http://***.hatenablog.com/",
"location": "Japan",
"email": null,
"hireable": null,
"bio": null,
"public_repos": 18,
"public_gists": 10,
"followers": 42,
"following": 19,
"created_at": "2010-11-06T08:30:14Z",
"updated_at": "2017-08-25T22:28:10Z"
}このAPIには、誰からでもアクセスできる情報しか含まれていないため、プライベートリポジトリの情報などは含まれていません。そのような情報にAPIからアクセスするには、アクセス元を証明するための認証を行う必要があります。
次回は、トークンを使った認証や、パラメータを指定したカスタマイズ方法などについて解説します。