REST API とは何か？について「最近話題の API や REST API ってなに? ~基礎編~」で記事を作成させていただきました。
今回は REST API についてもう少し詳細に紹介していきます。
REST API は、要求と応答の両方を設計しています。
要求：
アプリケーションなどのユーザーは GET などの「HTTP 動詞」を使用して、サービスを実行しているリソースへの「HTTP リクエスト」を持った要求を発行します。
その時、「リクエストヘッダー」、「リクエストペイロード」を必要に応じて添付します。
応答：
API リソースから「HTTP レスポンス」、「レスポンスヘッダー」、「レスポンスペイロード」を含む応答をユーザーへ返します。
以下、「ヘッダー」や「ペイロード」といった REST API を構成する要素について説明していきますが、聞きなれない単語が並んでわかりにくいと思う方もいると思います。
最初に、REST API の構造を「フォーム入力によって引っ越しセンターへ問い合わせする」に置き換えて表現してみます。
少し想像しやすくなったでしょうか？
それでは、REST API の構造について以下順を追って記載します。
1. HTTP リクエスト
2. HTTP レスポンス
3. 認証
4. ヘッダー
5. ペイロード
1. HTTP リクエスト
「HTTP リクエスト」とは「何に対するどのような処理か」を表しています。
冒頭の「引っ越しセンター」の例では、「見積もりの作成」のように、「見積もり」に対して「作成する」ことを要求している（問い合わせしている）ことがわかります。
この「何に対する」を API までのリソースパス、「処理」を HTTP 動詞と呼びます。
REST API の要求を発行する際、リソースパスと対する HTTP 動詞を設定する必要があります。
※「HTTP 動詞」「リソースパス」については「最近話題の API や REST API ってなに? ~基礎編~」でも記載しています
「リソースパス」は API の仕様になるため、提供されている仕様書を確認します。
対する「HTTP 動詞」は一般的なもので、「リソースパス」によって使用できる「HTTP 動詞」は異なります。
REST API に設定する HTTP 動詞は以下のものがあります。
| HTTP 動詞 | Action | |
|---|---|---|
| POST | 作成 | |
| GET | 取得 | |
| PUT | 更新 | |
| PATCH | 更新 | |
| DELETE | 削除 |
「引っ越しセンター」の例では、「見積もり」には「作成」しか使用できませんが、「予約」には「作成」「参照」「変更」「削除」が可能であることがフォーム（仕様書）から確認できます。
Webex の API である、「Webex ユーザーの登録者リストを取得する」APIを例に確認していきます。
ユーザーの一覧を取得したい場合は HTTP Request が「/v1/people」となりますが、「/v1/people」はリストの「取得」と「作成」の2パターンあります。
今回は「ユーザーリストの取得」を要求したいため、HTTP 動詞「GET」を設定して URI「GET https://webexapis.com/v1/people」を送信することで「取得」の API 要求を行うことができます。
2. HTTP レスポンス
リクエストの送信結果を、API リソースから受信します。
「引っ越しセンター」の例では、返信された回答内容に記載された「お問い合わせ対応状況」が該当します。
有効な REST API リクエストを要求した場合、通常は「200 OK」を応答の「HTTP レスポンス」として受信します。
リクエストが有効ではなかった場合、例えば「HTTP リクエスト」が存在しないものだった場合は「404 Not Found」を「HTTP レスポンス」として受信します。
主な「HTTP レスポンス」を以下に記載します。
| Status Code | Status Message | Meaning | |
|---|---|---|---|
| 200 | OK | 問題ありません | |
| 201 | Created | 新しいリソースが作成されました | |
| 400 | Bad Request | リクエストが無効です | |
| 401 | Unauthorized | 認証がないか、有効ではない | |
| 403 | Forbidden | リクエストが確認できましたが、許可されませんでした | |
| 404 | Not Found | リソースが見つかりません | |
| 500 | Internal Server Error | サーバーに問題があります | |
| 503 | Service Unavailable | サーバーがリクエストを完了できません |
3. 認証
「HTTP レスポンス」の一覧にある「401 Unauthorized」のとおり、API を使用するには認証が必要になります。
この認証情報は後述する「リクエストヘッダー」に含まれる情報です。
「引っ越しセンター」の例では、設定情報（リクエストヘッダー）の一部である「お客様番号」が該当します。
「お客様番号」を使って、「お問い合わせ可能なユーザーであるか？」「問い合わせ内容は受付可能か？」などを判断できますね。
一部の API は認証不要で使用することができますが、ほとんどの API は認証を必要としています。
認証の取得方法は各 API により異なっており、シスコではユーザー名とパスワードを使用した一般的な認証方法もあれば、OAuth を使用したアクセストークンによる認証方法もあります。
※OAuth については「最近話題の API の認証ってなに? ~OAuth編~」にて記事にしています
Webex API は、OAuth認可コードを発行し、API 呼び出し用の Access token と、期限更新用の Refresh token を作成しています。
Meraki の場合、API アクセスを有効にすると、クライアントはプログラムで使用するための API キーを生成しています。
4. ヘッダー
「ヘッダー」には API を使用するための設定情報を設定します。
要求と応答はそれぞれ、ヘッダーを使用してシステム間の設定を共有しています。
「引っ越しセンター」の例では、「やり取りする言語」「操作した日時」「操作者」といったシステム的な設定内容が該当します。
認証情報が必要な API の場合は、「認証情報」を「リクエストヘッダー」に含んで送信する必要があります。
以下、ヘッダーの一例です。
| ヘッダー | 例 | 効果 | |
|---|---|---|---|
| Content-Type | application/json | リクエストペイロードのデータの形式を指定します | |
| Accept | application/json | レスポンスペイロードに要求するデータ形式を指定します | |
| Authorization | Bearer xxxxxxxxxxxxxx | 認証情報を設定します | |
| Date/Time Stamp | Thu Jan,4 17:02:23 CST 2018 | 要求または応答メッセージの日時を設定します |
5. ペイロード
「ペイロード」には API 固有情報を設定します。
要求と応答は、ペイロードを使用してシステム間で項目データをやり取りします。
「引っ越しセンター」の例では、「見積もり取得に必要な情報」を入力してもらい、「見積もりの結果」を返している部分が該当します。
※「ペイロード」は API によっては設定不要な場合もあります
また、例の回答は「英語」で記載されています。
このように質問や回答（ペイロード）の言語も指定可能で、言語の指定は「ヘッダー」で行っています。
※例では「日本語」「英語」となっていますが、実際に指定できるのは「JSON」「XML」といったデータ形式になります。
実際にペイロードに設定される内容を、WebexAIP の「ミーティングを作成する」API の仕様を使って確認していきます。
要求：
「Body Parameters」にミーティング作成時に必要な仕様が記載されています。
「Example」→「Request」を選択すると、「Body Parameters」の設定例が表示され、これがリクエストペイロードに設定する内容に該当します。
応答：
「Body Parameters」に下に「Response Properties」という項目が存在します。
この「Response Properties」はレスポンスペイロードに設定される項目の仕様です。
「Example」→「Response」を選択すると、「Response Properties」の設定例が表示され、これがリクエストペイロードに設定される内容に該当します。
ペイロードのデータ形式は通常 JSON または XML です。
JSON：
JavaScriptObjectNotation の略称です。
JSON は人が読める形式で設計された、テキストベースの軽量なデータ交換形式です。
多くの REST API は JSON でやり取りするように作成されています。
XML：
eXtensibleMarkup Language の略称です。
XML はマークアップ言語で、データ構造を表現するのに役立つ構文をしています。
データ形式は「Content-Type」「Accept」に設定されるため、ヘッダーの「Content-Type」や「Accept」を設定するとペイロードのデータ形式を指定することができます。
例えば、「Content-Type:application/json」とすれば、リクエストペイロードを JSON で通信することを指定できます。
今回は「REST API とは何か」について、REST API の構造を題材に記載させていただきました。
「Oauth」という認可のプロセスも登場し、ヘッダーやペイロード設定できるものも一例での紹介でした。
次回は実際にヘッダーやペイロードを設定して、REST API を動かして確認したいと思います。
参考：
DEVNET Learning Labs（What is REST? What are APIs?）
（https://developer.cisco.com/learning/lab/what-are-rest-apis/step/1
）
Webex の 使い方や TIPS、開発者向けの情報などは、「Webex Connect – Japan」というコミュニティで随時共有されています。Webex をもっと有効活用したいとお考えの方はぜひご参加ください。
Authors