REST API

REST APIは、リソースとその表現のやり取りを、RESTという設計上の考え方に沿って行うAPIです。RESTはソフトウェア構成への制約の組であり、HTTPで呼び出せるAPIすべてが、その制約を満たすとは限りません。[1]

RESTでは、扱う対象をどう表し、相互作用をどう統一するかを考えます。リソースと、そのやり取りを支える制約を分けると理解しやすくなります。[2]

リソースと表現

リソースは、文書や画像など、名前を付けて扱う対象です。実際の通信では、その対象の状態を示す表現をやり取りします。対象そのものと、送受信するデータを同一視しないことがポイントです。[2]

RESTを支える設計上の制約

RESTの制約は、通信と構成の役割をそろえるものです。Fieldingの論文では、次の制約を組み合わせて説明しています。[2]

• クライアント・サーバー：画面側の関心とデータ側の関心を分ける。[2]
• ステートレス：各要求に、その要求を理解するために必要な情報を含める。[2]
• キャッシュ：応答を再利用できるかを明示または暗示する。[2]
• 統一インターフェース：構成要素間のやり取りを共通の仕組みにそろえる。[2]
• 階層化システム：相互作用する層を制限し、構成を分ける。[2]
• コードオンデマンド：コードを取得・実行して機能を拡張する。これは任意の制約。[2]

HTTPメソッドは、対象へどのような要求を送るかを表します。次の表はRFC 9110に沿った一般的な意味で、個別APIの実装仕様とは分けて確認します。[3]

安全とは、要求の意味が基本的に読み取り用であることです。冪等とは、同じ要求を繰り返したときの意図された効果が、一度の要求と同じであることです。ログの記録などの副作用が一切ないことや、応答が毎回同じことを保証する意味ではありません。[3]

POSTは新規作成だけに限られず、PUTも部分更新専用ではありません。また、DELETEは保存データの物理消去を保証するメソッドではありません。個別APIで何が起きるかは、その提供元の仕様で確かめます。[3]

JSONは、APIで送受信する表現形式の一つです。RESTは設計上の考え方なので、JSONを使っていることだけでRESTの制約を満たすとは判断できません。[1][4]

APIの説明では、どの形式でデータを送るかと、リソースをどのような要求で扱うかを分けて確認すると、役割を混同しにくくなります。

利用時には、URLとメソッドだけでなく、アクセスの条件と応答の意味まで確認します。次は実装を読む前の確認観点です。

• 認証・権限：誰がどのリソースを操作できるか。
• 入力と出力：必要な項目、表現形式、返される状態をどう解釈するか。
• 失敗時の扱い：エラー応答をどう判断し、再送してよい要求か。
• 公開範囲：外部へ返してよいデータと、利用制限が定められているか。