REST APIについて

はじめに

今回はREST API（WebAPI）について学習を行ったのでまとめたいと思います。

WebAPIとは

そもそもWebAPIとは何なのかを知らなかったので超簡単に説明します。
Webサービスで提供している機能やデータを別のプログラムから利用できるようにするための規約またはその実装を指します。
公開されているWebAPIを使用することによりサービスを全て実装する必要が無くなるため開発のコストや時間を削減することができます。

身近なWebAPIには以下のようなものが挙げられます。

何らかの施設や飲食店のホームページなどにGoogle Mapが組み込まれているのはGoogle Map APIで実現されています。

REST APIとは

REST（REpresentational State Transfer ）の略で日本語に訳すと「分散型システムにおける設計原則群」となります。
すなわちAPIの設計ルールを意味しています。
RESTには以下6つの原則があり原則を満たした状態を「RESTful」と呼びます。

  1. クライアント/サーバー 　
    クライアント/サーバーアーキテクチャで構成されていること。 　
    クライアント側がサーバー側にリクエストを送りサーバー側はクライアント側にレスポンスを返す構成のことを指します。

  2. ステートレス 　
    各単独のリクエストで情報が成り立っている状態のことを指します。

    • サーバセッションは使用しない。
    • 状態はリクエストに全て含める。

  3. キャッシュ制御 　
    レスポンスは明示的または暗黙的にキャッシュ可能であることを指します。 　
    不必要なクライアント/サーバー間の通信を排除することでユーザー体験の向上、リソース効率の向上が見込めます。

  4. 統一インターフェイス 　
    4つの制約で成り立っています。

    • リソースの識別
      　URIを使用することによりサーバーに保存されたデータを識別する。
    • 表現を用いたリソース操作
      　クライアントからサーバーにリクエストを送る際に認証状などの追加情報を付与する。
    • 自己記述メッセージ
      　クライアント/サーバー間のメッセージの内容がヘッダーに記述されている。
    • アプリケーション状態エンジンとしてのハイパーメディア（HATEOAS）
      　レスポンスに現在の状態を踏まえて関連するハイパーリンクが含まれている。

  5. 階層化システム 　
    特定の機能や役割を持ったサーバー(コンポーネント)が相互作用するアーキテクチャを指します。 　
    多層アーキテクチャ構成にすることによって高い拡張性と再利用ができるメリットがあります。

  6. コードオンデマンド 　
    プログラムコードをダウンロードしてクライアント側で実行することを指します。

    • メリット
      リリース済みのクライアントに対して機能追加ができる。
      サーバーの負荷が下がる。
    • デメリット
      複数ブラウザなどのクライアント環境の想定を行う必要があり評価が複雑になる。

URIの設計

以下の原則について考慮しながらURIの設計を行う必要があります。
- 短く入力しやすい（冗長なパスを含まない） 　
× GET http://api.example.com/service/api/serch 　
apiが重複&意味のないserviceという単語が含まれています。 　
○ GET http://api.example.com/serch

  • できるだけ省略しない（人間が読んで理解できる） 　
    × GET http://api.example.com/sv/u 　
    sv、uが何を指しているのか理解できません。 　
    ○ GET http://api.example.com/users

  • すべて小文字であること（大文字小文字が混在していない）

  • 単語はハイフンでつなげること 　
    アンダースコアは下線を引くためのものでハイフンは単語を繋げるためのものです。 　
    そもそも単語を連結するくらいならURIを見直す必要があります。

  • 単語は複数形を利用すること 　
    URIで表現しているのは「リソースの集合」であるため複数形で表現します。

  • エンコードを必要とする文字を使わない 　
    URIから意味が理解できる必要があります。

  • サーバー側のアーキテクチャを反映しない 　
    × GET http://api.example.com/cgi-bin/get_user.php?id=12345 　
    サーバーサイドでphpが動いていることが予想でき悪意あるユーザーに脆弱性を突かれる危険があります。 　
    サーバーサイドのアーキテクチャは反映せず純粋で綺麗なURIとして設計する必要があります。 　
    ○ GET http://api.example.com/users/12345

  • 改造しやすい（Hackable） 　
    システム依存の設計では人が意味を理解できません。 　
    × GET http://api.example.com/items/alpha/12345 　
    × GET http://api.example.com/items/beta/23456 　
    alpha、betaなどの意味の分からない単語は含めないようにしなければなりません。 　
    たとえ裏側の動きがalphaサーバー、betaサーバーと別れていたとしてもAPI設計としては取り除くのが適切です。 　
    ○ GET http://api.example.com/items/12345

  • ルールが統一されていること 　
    一定のルールに従って設計することで間違いを防ぐことができます。 　
    × 友達情報取得 　
    GET http://api.example.com/friends?id=12345 　
    メッセージ投稿 　
    GET http://api.example.com/friends/12345/message 　
    友達情報を取得するAPIとしてクエリパラメーターを使用しているのに対してメッセージ投稿はパスパラメータとなっており統一されていません。 　
    ○ 友達情報取得 　
    GET http://api.example.com/friends/12345 　
    メッセージ投稿 　
    GET http://api.example.com/friends/12345/message

movieをリソースとしたURIの設計例

上述したURI設計の原則に則ってmovieをリソースとしてURIとHTTPメソッドを定義すると以下のようになります。 | URI | HTTP method | 動作内容 | | :----: | :----: | :----: | | /api/v1/movies | POST | movieデータの作成 | | /api/v1/movies | GET | movieデータの一覧を取得 | | /api/v1/movies/:id | GET | idで指定したmovieデータを取得 | | /api/v1/movies/:id | PUT | idで指定したmovieデータを更新 | | /api/v1/movies/:id | DELETE | idで指定したmovieデータを削除 |

おわりに

以上REST API（WebAPI）についてのまとめでした。 ご閲覧いただきありがとうございました。

Udemy - REST WebAPI サービス設計
Web APIとは？初心者にもわかる基本的な仕組みと活用方法