初心者向けREST APIの基礎 |じょるブログ

この記事では REST API の使い方、使用するのに最低限必要な知識について解説します。

そもそもAPIとは・・

APIとは Application Programming Interface の略で、一言で説明するなら個人・自社のソフトウェアの機能の一部を誰でも使えるようにするものです。（※APIを利用するのに許可が必要なAPIも存在します。）

例えばよく飲食店などのサイトでグーグルマップを使ってそのお店の所在地を表示させているサイトをよく見かけると思いますが、あれはグーグルのサービスであるグーグルマップを一般の人にも使用できるように、グーグルがグーグルマップのAPIを公開しており、それを使用することであのようにグーグルマップを表示させています。

RESTについて

RESTとはAPIの一種で、 Webシステムから容易にAPIにアクセスできるように設計されたAPIのことで、主に以下のような特徴があります。

ステートレスである
全ての情報が一意なURIで表現されている
情報を操作する命令が指定されている

・ステートレスである

ステートレスとは、ステート（状態）がレス（無い）通信方式のことです。

システムが現在の状態を表すデータなどを保持せず、入力の内容によってのみ出力が決定される方式。
http://e-words.jp/w/%E3%82%B9%E3%83%86%E3%83%BC%E3%83%88%E3%83%AC%E3%82%B9.html

簡単に説明すると、通信により送信されたデータはサーバー側に保持されることはないため、同じデータを送信した場合、毎回同じ出力が返ってくる通信方式のことです。

つまり、複数回の通信に分けてデータを送信することで得たいデータが出力されるのではなく、一度の通信で情報を得るのに必要なデータを一括で送り、出力を得る方式です。

・全ての情報が一意なURIで表現されている

まず、URI （Uniform Resource Identifier）とは

情報やサービス、機器など何らかの資源（リソース）を一意に識別するためのデータの書式を定義した標準の一つ。一般的にはインターネット上のデータやサービス、機器などの所在情報を表すために用いられることが多いが、対象はこれらに限定されず、また、所在情報だけでなく対象の識別情報を記述することができる。
http://e-words.jp/w/URI.html

というようなものであり、例えば以下のようなものです。

http://maps.google.com/maps/api/

URL （Uniform Resource Locator）との違いは、URLは場所を表すためのものであり、URIは名前や場所を表すためのものです。URLはURIの一種です。
なので、よく見るサイトのアドレスはURLでもあり、URIでもあります。

・情報を操作する命令が指定されている

2.で全ての情報が一意なURIで表現されていると記載しましたが、そのURIに対して HTTPメソッド と呼ばれるものを使用して命令を下すことで情報を得ることができるようになっており、得たい情報によりどの HTTPメソッド を使用すればいいかというものが定義されています。

HTTPメソッドには以下のようなものが存在します。
（※他にも存在しますが、以下の4つがよく使われます。）

メソッド	意味	CRUD
POST	URIに情報を追加	CREATE
GET	URIで指定した情報を取得	READ
PUT	URIで指定した情報を更新	UPDATE
DELETE	URIで指定した情報を削除	DELETE

ここで示したものはHTTPメソッドのうちの代表的なものであり、
CREATE 、READ 、UPDATE 、DELETE の頭文字をとり、CRUDと呼ばれています。

REST APIの利用方法

上記でRESTについて簡単に説明しましたが、聞きなれない言葉が多くいまいち理解できない方もいると思うので、実際に REST API を使用して、解説していきます。

今回は簡単にREST APIを使用することができる、グルナビAPIを例に解説していきます。このAPIでは指定した地域の飲食店のデータをjson形式で取得することができます。

一般的には、サーバーのプログラムからAPIを呼び出すことが多いのですが、こちらのサイトではWEB上でHTTPリクエストを送ることができます。
（※こちらのサイトはテストツールなので、WEB上以外からアクセスしようとするとエラーとなります。）

・エリアコードの取得

まず、地域を指定するためのエリアコードを取得します。

上記の画像のように、API名を都道府県マスタ取得APIに変更して”クエリを送信”をクリックすると、

このように下の灰色部分に json形式でサーバーから返ってきたデータが表示されます。

このデータのarea_codeの値（上記の図だとAREA150）をコピーしておきます。

・飲食店検索

続いて、実際にレストランのデータを取得してみます。

まず、API名をレストラン検索APIに変更します。次に、パラメーターに”area”を追加し、先ほどコピーしたエリアコードを隣に入力し、クエリを送信を実行します。

すると、

指定したエリアの店舗情報を取得できます。

GETとPOSTの違い

このAPIはGETメソッドを使用しています。

GETメソッドでは、”クエリを送信”の上に書かれているURIのように、

?xxx=xxx&xxx=xxx

といったようにベースとなるURIにパラメータを追記して、サーバーにパラメータ情報を送信します。これをURLパラメーターといいます。

GETメソッドはWEBサイトを閲覧するときにも使われているので、よくこのように？xxx=xxxといった情報が含まれているURLをみたことがあると思います。
（GETメソッドを実行する際に必ずパラメータが必要なわけではありません）

こういったサイトはこのパラメータの値によって表示させる情報を変更させたりしています。

WEBサイトでもフォームにデータを入力してデータを送信することもありますが、このような個人情報を取り扱う場合は一般的にはPOSTメソッドが使用されます。

GETメソッドだと、パラメータが見えてしまうというのとURIの長さに制限があるのが主な理由です。

CURLコマンド

HTTPメソッドの実行は、CURLコマンドを使用することで、コマンドプロンプトからも実行することが可能です。

・GETリクエスト

GETリクエストを行う場合はcurlの後ろにURIを指定します。

curl https://api/abc/

・POSTリクエスト

POSTリクエストを行う場合は -XPOST オプションを使用します。

curl -XPOST https://api/abc/

POSTリクエストを実行する際はヘッダーを指定することが多く、その場合は、 -H オプションを使用します。

curl -XPOST https://api/abc/ -H “Content-Type: application/json”

複数指定する場合は以下のように入力します。

curl -XPOST https://api/abc/ -H “Content-Type: application/json” -H “area: tokyo”

jsonなどのデータを送る場合は -d オプションを使用します。

curl -XPOST https://api/abc/ -H “Content-Type: application/json” -d “{“keyId”:”xxx”,”area”:tokyo}”

リクエストを手軽に行うことができるツール

僕はAPIのテスト実行をする場合は POSTMAN というソフトウェアを使用しています。

こちらのソフトは、POST、GETなど様々なリクエストができるのと、パラメータの指定も直観的にできます。

一度実行したリクエストは自動で保存されるので後で再度呼び出すことも可能なのでとても便利です。

GoogleのAPIなどを使用する際には OAuth認証と呼ばれる認証を行う必要があり、少し複雑な手順を踏む必要があります。そのような認証を行うAPIを実行する際は、このPOSTMANでもできなくはないですが、pythonなどプログラムから行ったほうが簡単です。