30代中盤・未経験からGoエンジニアを目指す人のブログ

～プログラミング関連、勉強法などから雑記まで赴くままに～

初学者がREST APIについて学んだのでまとめ

REST APIを勉強したてホヤホヤの私がどういった物かを説明するブログです。

そもそもAPIって何？

APIとは、
Application Programming Interface
の頭文字を取ったもので、機能やデータを外部から呼び出して利用できるよう定めた規約です

ではWeb APIとは？

Web APIとは、インターネット上、Webサービスで提供されている機能やデータを外からプログラムが読み取りやすい形で利用できるよう定めた規約またはその実装、になります。

REST API

そして登場するのがRESTです。
RESTとは、
REpresentational State Transfer
です。
日本語に直すと、『分散型システムにおける設計原則郡』
つまり、設計ルールになります。

この設計ルールはREST原則といい、REST原則には大きく6種類あります。

  • クライアント / サーバー
    クライアント側は画面(UI)をサーバー側はデータ処理、と分離させる 上記を分けることにより、クライアント側がトリガー、サーバー側はあくまで受け身の姿勢、となる

  • ステートレス
    各リクエストのやり取りに独立性(状態保存を敢えてしない)を持たせる事で、リクエスト単体を見るだけでどんな内容のやり取りか理解できる。
    つまり、サーバーはリクエスト単一だけでコンテキストを理解できる。
    これにより、単一のリクエスト以外見なくて良いため監視が容易、障害発生時にリクエストだけ回復すれば良いので障害復旧が容易になるというメリット。

  • キャッシュ制御
    クライアントはレスポンスをキャッシュできる。
    これにより、ユーザー体験・リソース効率・拡張性の向上が見込める。

  • 統一インターフェース
    標準的なHTTPメソッドを用いてリソースを操作する。
    システムアーキテクチャ全体が簡素化されてわかりやすくなり、異なるブラウザでも同じような画面を表示できる。

  • 階層化システム
    Web → AP → DBといった多層アーキテクチャ構成。
    実際にはWeb, AP, DBそれぞれが何台もありそれぞれ複雑に組み合わさっており、その一つ一つをコンポーネントという。
    このように各コンポーネントをカプセル化させることにより、進化と再利用が可能になる。

  • コードオンデマンド
    サーバー側を更新することでクライアントが自動的に新しい環境をダウンロードして実行できるといった特徴。
    リリース済みのクライアントに対して機能追加ができたり、クライアントに処理を譲渡出来るためサーバーの負担が下がるというメリットがある。

これらのREST原則に基づいて実装されたAPIを REST API といいます。

REST API 設計の一例

ここでは例として映画情報の一覧がまとまっているmovieリソースというものを想定し、
それに対しての操作(読み取り・作成・更新・削除)の関係を表にまとめてみました。
表内のURI欄は『http://api.example.com/』までを省略し、それ以降のURIを記述しています。

操作 URI HTTPメソッド
映画情報一覧の取得 /movies GET
特定の映画情報の取得 /movies/123456 GET
映画の新規登録 /movies POST
特定の映画情報の更新 /movies/123456 PUT
特定の映画情報の削除 /movies/123456 DELETE

上記、/moviesは映画情報の一覧(リソース)を表し、/123456はその映画情報一覧の中の特定の映画情報(リソース)を表すパスパラメータになります。

URI設計のポイント

  • 短く入力しやすい、冗長なパスを含まない
    悪い例：GET http://api.example.com/service/api/search (apiが重複してる、/serviceが無駄)
    良い例：GET http://api.example.com/search (このように短くシンプルに)

  • 人が読んで理解できる
    悪い例：GET http://api.example.com/sv/u (利用者がsvやuを読んでも理解し難い)
    良い例：GET http://api.example.com/users (初見でも読んで理解できるURIに)

  • 大文字小文字が混在していない(すべて小文字)
    ※例省略

  • 単語は複数形を利用する
    例：先程の表でmovieリソースとは映画情報というリソースが集合しているもののため『/movie』ではなく、複数形の『/movies』としています。

  • エンコードを必要とする文字を使わない(日本語などを使わない)
    悪い例：以下は『ムービー』と日本語で書いた場合のエンコードした文字が含まれるバッドパターンなURIです
    GET http://api.example.com/%E3%83%A0%E3%83%BC%E3%83%93%E3%83%BC (人が読んで理解できない)

まとめ

REST API設計の一例でまとめたようにREST原則に基づいてシンプルに設計することが重要になります。
私もまだ勉強したばかりなので実際にRESTに基づいてAPIを設計するときは漏れがないよう気をつけたいと思います。