メインコンテンツまでスキップ

REST API

Overview​

REST APIについてまとめるセクション。
一般的には HTTP でアクセスでき、データを XML や JSON を返すAPI。

有名REST API​

REST API設計者のための有名APIのURL例

概要​

RESTはRepresentational State Transferという用語の略で、2000年にロイ・フィールディング（Roy Fielding）の博士論文で初めて紹介されました。ロイ・フィールディングは、HTTPの主な著者の一人で、Web（HTTP）の設計の優秀さに比べて適切に使用されていない様子を残念に思い、Webの利点を最大限に活用できるアーキテクチャとしてRESTを発表したそうです。

構成​

REST APIは次のように構成されている。

  • 資源（RESOURCE）URI
  • 行為（Verb）HTTPメソッド
  • 表現（Representations）

設計ガイド​

REST API設計時、もっとも重要な項目は、次の2つに要約できる。

  1. URIは情報の資源を表現しなければならない。
  2. 資源の行為は、HTTPメソッド（GET、POST、PUT、DELETE）で表現する。

REST APIでよく使用される単語について​

コレクションが、そのURLの対する全体 /users
リソースがそのURLの詳細 users/:id

コレクション RESTfulなルーティングにおいてリソースのコレクションに対してルーティングを定義するために使われます。
コレクションに対するルーティングは、モデル全体に適用されるアクションに対して定義できる。

例 :indexアクションはコレクションに適用されるアクションであり、:showアクションはリソースに適用されるアクションです。:collectionオプションを使用すると、コントローラーで定義されたアクションに対して、URLに:idを含めないでアクセスすることができます。

リソース特定方法​

URLのパスパラメーターとリクエストボディを同時に送信することは現実的。
実際、RESTful APIの設計においては、パスパラメーターを使ってリソースを指定し、リクエストボディにデータを含めて操作することが一般的。
たとえば、フォローするAPIであれば、/user/:userId/follow というURLを使って、指定したユーザーをフォローできる。リクエストボディには何も含めない場合もあります。

パラメーター種類​

  • クエリパラメーター
  • パスパラメーター

パスパラメーター​

/user/:userId という形式のURLは、パスパラメーター

クエリパラメーター​

クエリパラメーターは ? を使ってURLに付与するものです。

メソッド設計方法​

PUT​

PUTメソッドでは、リクエストボディにデータを含めて送信することが一般的です。PUTメソッドを使用する場合は、更新内容はリクエストボディに含めることができます。

レスポンス​

POSTやPUT, DELETE

  1. 更新したデータを返す。 更新したデータを return するという方法。こんな風にデータが直りましたと示す。
  2. HTTP STATUSで 201 や 204 を返してあげる方法。 201 は情報が作成された意味 204 は通信は成功してるけど戻り値がないという意味

DELETEのレスポンス​

結局データはないので 204 を返す。

チェックリスト​

  • URLが短く入力しやすくなっているか
  • URIが人間が読んで理解できるようになっているか
  • URIが小文字のみで構成されているか
  • URIが改造しやすくなっているか
  • URIにサーバ側のアーキテクチャーが反映されていないか
  • URIのルールが統一されているか
  • 適切なHTTPメソッドは利用しているか
  • URIで利用する単語は多くのAPIで同じ意味に利用されているものを選んでいるか
  • URIで使われている名詞は複数形になっているか
  • URI中にスペースやエンコードを必要とする文字が入っていないか
  • URI中の単語はハイフンでつないでいるか
  • ページネーションは適切に設計されているか
  • ログインにはOAuth2.0を利用しているか
  • レスポンスデータ形式はJSONがデフォルトになっているか
  • データ形式の指定にはクエリパラメーターを使う方法をサポートしているか
  • 不要なJSONPに対応していないか
  • レスポンスのデータ内容はクライアントから指定できるようになっているか
  • レスポンスデータに不要なエンベロープが入っていないか
  • レスポンスデータの構造は可能な限りフラットになっているか
  • レスポンスデータが配列ではなくオブジェクトになっているか
  • レスポンスのデータ名として多くのAPIで同じ意味に利用されている一般的な単語を選んでいるか
  • レスポンスのデータ名はなるべく少ない単語数で表現しているか
  • レスポンスのデータ名として複数の単語を連結する場合、その連結方法はAPI全体で統一されているか
  • レスポンスのデータ名として変な省略系を使用していないか
  • レスポンスのデータ名の単数形・複数形はデータの内容と合っているか
  • エラー時のレスポンスはクライアントが原因を切り分けられるような情報を含んでいるか
  • エラーの際にHTMLが返っていないか
  • 適切なステータスコードが変えるようになっているか
  • メンテナンス時には503を返すようになっているか
  • 適切なメディアタイプを返しているか
  • 必要な場合はCORSに対応しているか
  • クライアントが適切にキャッシュを行えるようにCache-Controller,Etag,Last-Modified,Varyなどのレスポンスヘッダを返しているか
  • キャッシュをさせたくないデータにはCache-Controller: no-cacheが付けられているか
  • APIはバージョンで管理されているか
  • APIのバージョンはセマンティックバージョニングに沿ったものになっているか
  • メジャーバージョン番号がURIに入っており、一目でわかるようなっているか
  • APIの提供を終了する際のことを考慮に入れているか
  • APIの査定提供期間をドキュメントに示しているか
  • HTTPSでAPIを提供しているか
  • JSONのエスケープをきちんと行なっているか
  • JSONはX-Requested-Withヘッダを認識するなどSCRIPT要素では読み込めないようなっているか
  • ブラウザからアクセスさせるAPIではXSRFトークンを利用しているか
  • APIが受け取るパラメータはきちんと不正値（マイナスの値）などをチェックしているか
  • リクエストが再送信されてもデータを再度更新してしまわないようになっているか
  • レスポンスにセキュリティ対策用の各種ヘッダをきちんとつけているか
  • レートリミットによる制限をしているか
  • レートリミットの制限回数は想定されるユースケースに対して少なすぎないか
に最終更新