RESTAPIの理解と使用

TwitterやGithubなど、インターネット上の別のソースからデータを取得することを考えている場合は、「RESTAPI」という用語に出くわす可能性が高くなります。 しかし、REST APIとは何ですか？ それはあなたのために何ができますか？ それをどうやって使いますか？

この記事では、APIドキュメントを読んで効果的に使用するために、RESTAPIについて知っておく必要のあるすべてのことを学びます。

RESTAPIとは

Youtubeでバットマンに関する動画を見つけようとしているとしましょう。 Youtubeを開き、検索フィールドに「バットマン」と入力してEnterキーを押すと、バットマンに関するビデオのリストが表示されます。 RESTAPIも同様に機能します。 何かを検索すると、要求しているサービスから結果のリストが返されます。

APIは、アプリケーションプログラミングインターフェイスです。 これは、プログラムが相互に通信できるようにする一連のルールです。 開発者はサーバー上にAPIを作成し、クライアントがそれと通信できるようにします。

RESTは、APIがどのように見えるかを決定します。 これは「RepresentationalStateTransfer」の略です。 これは、開発者がAPIを作成するときに従う一連のルールです。 これらのルールの1つは、特定のURLにリンクすると、データの一部（リソースと呼ばれる）を取得できるようにする必要があることを示しています。

各URLはリクエストと呼ばれ、返送されるデータはレスポンスと呼ばれます。

リクエストの構造

リクエストは次の4つの要素で構成されていることを知っておくことが重要です。

1. エンドポイント
2. 方法
3. ヘッダー
4. データ（または本文）

エンドポイント（またはルート）は、要求したURLです。 それはこの構造に従います：

 root-endpoint/ ? root-endpoint/ ? root-endpoint/ ?

ルートエンドポイントは、リクエスト元のAPIの開始点です。 GithubのAPIのルートエンドポイントはhttps://api.github.comですが、ルートエンドポイントのTwitterのAPIはhttps://api.twitter.comです。

パスによって、要求しているリソースが決まります。 これは、サービスの場合は1を押し、別のサービスの場合は2を押し、さらに別のサービスの場合は3を押すように要求する自動留守番電話のように考えてください。

Webサイトの一部にリンクするのと同じように、パスにアクセスできます。 たとえば、Smashing Magazineの「JavaScript」でタグ付けされたすべての投稿のリストを取得するには、 https://www.smashingmagazine.com/tag/javascript/に移動します。 https://www.smashingmagazine.com/がルートエンドポイントで、 /tag/javascriptがパスです。

使用可能なパスを理解するには、APIドキュメントを確認する必要があります。 たとえば、GithubのAPIを介して特定のユーザーによるリポジトリのリストを取得するとします。 ドキュメントには、次のパスを使用してこれを行うように指示されています。

 /users/:username/repos

パス上のコロン（ :は、変数を示します。 これらの値は、リクエストを送信したときの実際の値に置き換える必要があります。 この場合、 :usernameを、検索しているユーザーの実際のユーザー名に置き換える必要があります。 Githubアカウントを検索している場合は、 :usernameをzellwkに置き換えます。

Githubで私のリポジトリのリストを取得するためのエンドポイントは次のとおりです。

 https://api.github.com/users/zellwk/repos

エンドポイントの最後の部分はクエリパラメータです。 技術的には、クエリパラメータはRESTアーキテクチャの一部ではありませんが、多くのAPIがそれらを使用していることがわかります。 したがって、APIの読み方と使用方法を完全に理解できるように、APIについても説明します。 クエリパラメータには、キーと値のペアを使用してリクエストを変更するオプションがあります。 それらは常に疑問符（ ? ）で始まります。 次に、各パラメーターペアは、次のようにアンパサンド（ & ）で区切られます。

 ?query1=value1&query2=value2

Githubでユーザーのリポジトリのリストを取得しようとすると、リクエストに3つの可能なパラメーターを追加して、提供された結果を変更します。

最近プッシュしたリポジトリのリストを取得したい場合は、 sortをpushに設定できます。

 https://api.github.com/users/zellwk/repos?sort=pushed

このエンドポイントが機能するかどうかをどうやって知るのですか？ さて、それを試してみる時が来ました！

curlを使用したエンドポイントのテスト

任意のプログラミング言語でリクエストを送信できます。 JavaScriptユーザーは、FetchAPIやjQueryのAjaxメソッドなどのメソッドを使用できます。 RubyユーザーはRubyのNet :: HTTPクラスを使用でき、PythonユーザーはPythonRequestsを使用できます。 等々。

この記事では、cURLと呼ばれるコマンドラインユーティリティを使用します。 APIドキュメントは通常cURLを参照して記述されているため、cURLを使用します。 cURLの使用方法を理解していれば、APIドキュメントを理解するのに問題はありません。 そうすれば、好みの言語で簡単にリクエストを実行できます。

続行する前に、マシンにcURLがインストールされていることを確認する必要があります。 ターミナルを開き、 curl -versionと入力します。 このコマンドは、システムにインストールしたcURLのバージョンをチェックします。

 curl --version

cURLがインストールされていない場合は、「コマンドが見つかりません」というエラーが発生します。 このエラーが発生した場合は、先に進む前にcurlをインストールする必要があります。

cURLを使用するには、 curlと入力し、その後に要求しているエンドポイントを入力します。 たとえば、Githubのルートエンドポイントを取得するには、次のように入力します。

 curl https://api.github.com

Enterキーを押すと、Githubから次のような応答が返されます。

ユーザーのリポジトリのリストを取得するには、上記で説明したように、エンドポイントを正しいパスに変更します。 私のリポジトリのリストを取得するには、次のコマンドを使用できます。

 curl https://api.github.com/users/zellwk/repos

cURLにクエリパラメータを含める場合は、 ?の前に円記号（ \ ）を付けてください。 および=文字。 これは? および=は、コマンドラインの特殊文字です。 それらを通常の文字として解釈するには、コマンドラインでそれらの前に\を使用する必要があります。

 curl https://api.github.com/users/zellwk/repos\?sort\=pushed

いずれかのコマンドを使用して、リクエストを実行してみてください。 Githubのルートエンドポントで見たものと同様の応答が得られます（ただし、より多くのデータがあります）。

JSON

JSON（JavaScript Object Notation）は、RESTAPIを介してデータを送受信するための一般的な形式です。 Githubから返送される応答もJSONとしてフォーマットされます。

JSONオブジェクトはJavaScriptオブジェクトのように見えます。 JSONでは、各プロパティと値は次のように二重引用符で囲む必要があります。

 { "property1": "value1", "property2": "value2", "property3": "value3" }

リクエストの構造に戻る

リクエストは4つの部分で構成されていることを学びました。

1. エンドポイント
2. 方法
3. ヘッダー
4. データ（または本文）

リクエストを構成する残りの部分を見ていきましょう。

方法

メソッドは、サーバーに送信するリクエストのタイプです。 以下の5つのタイプから選択できます。

• GET
• POST
• PUT
• PATCH
• DELETE

これらのメソッドは、あなたが行っているリクエストに意味を与えます。 これらは、 Create 、 Read 、 Update 、 Delete （CRUD）の4つの可能なアクションを実行するために使用されます。

APIは、各リクエストを使用するリクエストメソッドを通知します。 たとえば、ユーザーのリポジトリのリストを取得するには、 GETリクエストが必要です。

ユーザーからリポジトリのリストを取得するには、GETリクエストが必要です。 新しいGithubリポジトリを作成するには、 POSTリクエストが必要です。

cURLでリクエストメソッドを設定するには、 -Xまたは--requestを記述し、その後にリクエストメソッドを記述します。 以下のこのコマンドは、cURLを介してリポジトリを作成しようとします。

 curl -X POST https://api.github.com/user/repos

このリクエストを実行してみてください。 認証が必要であることを通知する応答が表示されます。 （認証については後で詳しく説明します）。

 { "message": "Requires authentication", "documentation_url": "https://developer.github.com/v3" }

ヘッダー

ヘッダーは、クライアントとサーバーの両方に情報を提供するために使用されます。 認証やボディコンテンツに関する情報の提供など、さまざまな目的に使用できます。 有効なヘッダーのリストは、MDNのHTTPヘッダーリファレンスにあります。

HTTPヘッダーは、コロンで区切られたプロパティと値のペアです。 次の例は、サーバーにJSONコンテンツを予期するように指示するヘッダーを示しています。

 "Content-Type: application/json". Missing the opening ".

-Hまたは--headerオプションを使用して、curlを使用してHTTPヘッダーを送信できます。 上記のヘッダーをGithubのAPIに送信するには、次のコマンドを使用します。

 curl -H "Content-Type: application/json" https://api.github.com

（注：Content-Typeヘッダーは、GithubのAPIが機能するための要件ではありません。これは、cURLでヘッダーを使用する方法を説明するための単なる例です）。

送信したヘッダーを表示するには、次のように、リクエストを送信するときに-vまたは--verboseオプションを使用できます。

 curl -H "Content-Type: application/json" https://api.github.com -v 

ここで、 *はcURLによって提供される追加情報を指します。 >はリクエストヘッダーを指し、 <はレスポンスヘッダーを指します。

データ（または「本体」）

データ（「本文」または「メッセージ」と呼ばれることもあります）には、サーバーに送信する情報が含まれています。 このオプションは、 POST 、 PUT 、 PATCH 、またはDELETEリクエストでのみ使用されます。

cURLを介してデータを送信するには、 -dまたは--dataオプションを使用できます。

 curl -X POST <URL> -d property1=value1

複数のデータフィールドを送信するには、複数の-dオプションを作成できます。

 curl -X POST <URL> -d property1=value1 -d property2=value2

理にかなっている場合は、リクエストを複数行に分割して、読みやすくすることができ\ 。

 curl -X POST <URL> \ -d property1=value1 \ -d property2=value2

サーバーを起動する方法を知っている場合は、APIを作成して独自のデータをテストできます。 わからないが、試してみる勇気がある場合は、この記事に従って、Node、Express、およびMongoDBを使用してサーバーを作成する方法を学ぶことができます。

サーバーを起動したくない場合は、Requestbin.com（無料です！ ）にアクセスして、「エンドポイントの作成」をクリックします。 次の図に示すhttps://requestb.in/1ix963n1のように、リクエストのテストに使用できるURLが提供されます。

リクエストをテストする場合は、必ず独自のリクエストビンを作成してください。 リクエストビンは、作成後48時間だけ開いたままになります。 この記事を読む頃には、私が上で作成したビンはずっとなくなっているでしょう。

次に、リクエストビンにデータを送信してから、ビンのWebページを更新してみてください。 次のようなデータが表示されます。

 curl -X POST https://requestb.in/1ix963n1 \ -d property1=value1 \ -d property2=value2 

デフォルトでは、cURLは、ページの「フォームフィールド」を介して送信されたかのようにデータを送信します。 JSONデータを送信する場合は、 Content-Typeをapplication/jsonに設定する必要があります。また、データを次のようにJSONオブジェクトとしてフォーマットする必要があります。

 curl -X POST https://requestb.in/1ix963n1 \ -H "Content-Type: application/json" \ -d '{ "property1":"value1", "property2":"value2" }' 

そして、それは（ほぼ！）リクエストの構造について知る必要があるすべてです。

さて、GithubのAPIを介してPOSTリクエストを送信しようとすると、「認証が必要です」というメッセージが表示されたことを覚えていますか？ それは、 POSTリクエストを実行する権限がないためです。

認証

あなたはあなたの許可なしに誰もあなたの銀行口座にアクセスすることを許可しませんか？ 同じ考え方で、開発者は、許可された場合にのみアクションを実行できるようにするための対策を講じています。 これにより、他人があなたになりすますことを防ぎます。

POST 、 PUT 、 PATCH 、およびDELETE要求はデータベースを変更するため、開発者はほとんどの場合、それらを認証の壁の後ろに置きます。 場合によっては、 GETリクエストで認証も必要になります（たとえば、銀行口座にアクセスして現在の残高を確認する場合など）。

Webでは、自分自身を認証する主な方法が2つあります。

1. ユーザー名とパスワード（基本認証とも呼ばれます）
2. シークレットトークン付き

シークレットトークン方式にはoAuthが含まれており、Github、Google、Twitter、Facebookなどのソーシャルメディアネットワークで自分自身を認証できます。

この記事では、ユーザー名とパスワードを使用した基本認証の使用方法のみを学習します。 oAuthを使用した認証に興味がある場合は、ZackGrossbartによる「OAuth2とFacebookでのログインについて知っておくべきこと」を読むことをお勧めします。

cURLを使用して基本認証を実行するには、次のように、 -uオプションに続けて、ユーザー名とパスワードを使用できます。

 curl -x POST -u "username:password" https://api.github.com/user/repos

上記のリクエストで、ユーザー名とパスワードを使用して自分自身を認証してみてください。 認証に成功すると、応答が「認証が必要」から「JSONの解析に問題があります」に変わります。

これは、サーバーにデータ（すべてのPOST 、 PUT 、 PATCH 、およびDELETE要求に必要）をまだ提供していないためです。

これまでに学んだ知識があれば、上記のコードを編集して、cURLを介してGithubリポジトリを作成できるはずです。 自分で試してみてください！

それでは、HTTPステータスコードとエラーメッセージについて説明しましょう。

HTTPステータスコードとエラーメッセージ

「認証が必要」や「JSONの解析に問題がある」など、以前に受信したメッセージの一部はエラーメッセージです。 リクエストに問題がある場合にのみ表示されます。 HTTPステータスコードを使用すると、応答のステータスをすばやく確認できます。 100+から500+の範囲。 一般に、番号は次の規則に従います。

1. 200+は、リクエストが成功したことを意味します。
2. 300+は、リクエストが別のURLにリダイレクトされることを意味します
3. 400+は、クライアントから発生したエラーが発生したことを意味します
4. 500+は、サーバーから発生したエラーが発生したことを意味します

verboseオプション（ -vまたは--verbose ）またはheadオプション（ -Iまたは--head ）を使用して、応答のステータスをデバッグできます。

たとえば、ユーザー名とパスワードを指定せずにPOSTリクエストに-Iを追加しようとすると、401ステータスコード（未承認）が表示されます。

データが間違っているか欠落しているためにリクエストが無効である場合、通常は400ステータスコード（不正なリクエスト）を受け取ります。

特定のHTTPステータスコードの詳細については、MDNのHTTPステータスリファレンスを参照してください。

APIバージョン

開発者はAPIを時々更新します。 場合によっては、APIが大幅に変更され、開発者がAPIを別のバージョンにアップグレードすることを決定することがあります。 これが発生し、アプリケーションが機能しなくなった場合、通常は古いAPIのコードを記述したことが原因ですが、リクエストは新しいAPIを指しています。

特定のAPIバージョンをリクエストするには2つの方法があります。 どちらを選択するかは、APIの記述方法によって異なります。

これらの2つの方法は次のとおりです。

1. エンドポイントで直接
2. リクエストヘッダー内

たとえば、Twitterは最初の方法を使用します。 執筆時点では、TwitterのAPIはバージョン1.1であり、エンドポイントから明らかです。

 https://api.twitter.com/1.1/account/settings.json

一方、Githubは2番目の方法を使用します。 執筆時点では、GithubのAPIはバージョン3であり、 Acceptヘッダーを使用してバージョンを指定できます。

 curl https://api.github.com -H Accept:application/vnd.github.v3+json

まとめ

この記事では、REST APIとは何か、およびcURLを使用してGET 、 POST 、 PUT 、 PATCH 、およびDELETEメソッドを使用してリクエストを実行する方法を学習しました。 さらに、 -uオプションを使用してリクエストを認証する方法、およびHTTPステータスの意味についても学習しました。

この記事がRESTAPIについて十分に学び、アプリケーションを作成するときにそれらを流暢に使用できるようになることを願っています。 ご不明な点がございましたら、お気軽に私のブログにアクセスするか、以下にコメントを残してください。