TERM 028
REST API
リソースをHTTPで操作するAPI設計スタイル
REST APIは、扱う対象をResourceとしてURLで表し、HTTP MethodとStatus Codeを使って状態を取得・作成・変更・削除するAPIの設計スタイルです。
HTTPとリソース指向を用いて設計するAPIのスタイルの全体像。
CONTENTSこの記事の目次＋
QUICK OVERVIEW
30秒でつかむ
操作対象
URIで一意に識別できる業務上の概念を設計します。
要求ごとに完結
処理に必要な情報を各リクエストへ含め、サーバー間で扱いやすくします。
標準の意味を使う
Method、Status、Cacheの既存ルールを活かします。
01 — DEFINITION
REST APIとは
何か
REST APIは、扱う対象をResourceとしてURLで表し、HTTP MethodとStatus Codeを使って状態を取得・作成・変更・削除するAPIの設計スタイルです。
02 — HOW IT WORKS
仕組みを
3段階で見る
細部へ入る前に、入力から結果までの役割を順番に捉えます。
対象をURLで示す
/orders/42のように名詞として識別する。
→操作をMethodで示す
GET、POST、PATCH、DELETEなどを選ぶ。
→表現を返す
状態コードとJSONなどで現在の表現を返す。
REST APIを理解するときの、最小の処理単位です。
03 — ESSENTIALS
押さえるべき
3つの要点
名前だけでなく、この3点の関係まで理解すると実装へつなげやすくなります。
操作対象
URIで一意に識別できる業務上の概念を設計します。
要求ごとに完結
処理に必要な情報を各リクエストへ含め、サーバー間で扱いやすくします。
標準の意味を使う
Method、Status、Cacheの既存ルールを活かします。
04 — REAL WORLD EXAMPLE
注文リソースを更新する
注文42の配送先だけを変更します。
- 01
PATCH /orders/42へ変更項目を送る
- 02
認可と入力を確認して更新する
- 03
更新後の表現または204を返す
05 — WATCH OUT
理解するときの
注意点
便利な仕組みほど、守備範囲と失敗の前提を明確にします。
動詞だらけのURLにしない
/updateOrderより、ResourceとHTTP Methodの役割を分けます。
一貫したエラー形式を持つ
入力誤り、競合、権限不足を機械的に扱える形で返します。
IN ONE SENTENCE
REST APIとは？
HTTPとリソース指向を用いて設計するAPIのスタイル。