ゆめさくコード

API設計の原則

luagate/api-design-introAPI設計入門26 枚Web 開発
スライド103触れる図解124レッスンの導入6

上から下へ、全 26 枚そのまま並べています。

発表モードで開く

API設計入門

API設計の原則

使いやすいAPIとは 〜RESTfulな設計〜

1
1

目次

今日の流れ

1. 良いAPIの条件とリソース指向

2. メソッドとステータスコードの使い分け

3. 命名・バージョン管理・認証

4. エラー設計とドキュメント・良し悪し

5. まとめと振り返り

2
2
API設計入門 - イントロ

今日のゴール

この時間で身につけてほしいことです。RESTfulなAPI設計の基本を理解しましょう。

  • 良いAPIに共通する条件が分かる
  • リソース指向のURL設計が分かる
  • メソッドとステータスコードの使い分けが分かる
  • 命名・バージョン管理の考え方が分かる
  • 良い例と悪い例を見分けられる
10
3
API設計入門 - イントロ

復習 REST API

以前学んだREST APIを思い出しましょう。今日はその「設計の質」を高める話です。

REST API（おさらい）

データを「リソース（資源）」として捉え、URLで名前をつけ、HTTPメソッドで操作するAPI。今日は、このRESTを使いやすく設計するためのコツを学ぶ。

・リソースは扱いたいデータのまとまり

・URLはリソースの住所

・操作はメソッドで表す

・この基本の上に良い設計を積む

11
4
API設計入門 - イントロ

良いAPIの3つの条件

使いやすいAPIには共通点があります。大きく3つの観点で押さえましょう。

分かりやすい
  • URLを見れば用途が分かる
  • ドキュメント無しでも推測できる
  • 一貫した名づけ
予測できる
  • 似た操作は似た形
  • ルールが統一されている
  • 驚きが少ない
変えやすい
  • バージョンで安全に進化
  • 既存利用者を壊さない
  • 拡張しやすい
12
5
API設計入門 - イントロ

リソース指向の設計

RESTの土台は「データを名詞でとらえる」考え方です。URLは住所、操作はメソッドで表します。

リソース指向（Resource Oriented）

扱いたいデータを「リソース」という名詞で表し、URLでその住所を示す設計。何をするかはURLではなくメソッドで表すのが基本。

・URLは名詞だけにする（動詞を入れない）

・一覧はusers、個別はusers/1のように表す

・操作の種類はメソッドが担う

・住所と動作を分けて考える

13
6

API設計入門 - 基本

2

第2部 メソッドとステータス

操作と結果を正しく表す

20
7
API設計入門 - 基本

1回のやり取りの流れ

利用側がリクエストを送り、APIがメソッドに応じて処理し、ステータスとデータを返します。

  • 利用側がメソッドとURLを指定して送る
  • APIがリソースを操作する
  • 結果をステータスコードで伝える
  • 本文にデータを載せて返す
  • この一往復をきれいに設計する
21
8
API設計入門 - 基本

復習 HTTPメソッドの使い分け

以前学んだメソッドを設計の観点で整理します。操作の種類とメソッドを一致させます。

やること
URLの例

GET

取得する

/users や /users/1

POST

新しく作る

/users

PUT

まるごと更新

/users/1

DELETE

削除する

/users/1

22
9
API設計入門 - 基本

復習 ステータスコード

結果は数字のコードで伝えます。成功・失敗の種類を正しく返すのが良い設計です。

意味
使う場面

200 OK

成功

取得や更新がうまくいった

201 Created

作成成功

新しいリソースを作った

404 Not Found

見つからない

指定したリソースが無い

500 Server Error

サーバー側の不具合

処理中に問題が起きた

23
10
API設計入門 - 基本

べき等という考え方

同じ操作を何度繰り返しても結果が変わらない性質を「べき等」と言います。設計の判断材料です。

べき等（idempotent）

同じリクエストを何度送っても、最終的な結果が同じになる性質。GETやPUTやDELETEはべき等で、POSTは繰り返すと増えてしまうため注意が必要。

・GETは何度取得しても状態が変わらない

・PUTは同じ内容なら結果が同じ

・DELETEは消した後にもう一度送っても消えたまま

・POSTは繰り返すと二重作成の恐れ

24
11

API設計入門 - 設計

3

第3部 命名とバージョンと認証

進化と安全を両立する

30
12
API設計入門 - 設計

命名のルール

・URLの命名には型があります。一貫した名づけが使いやすさを大きく左右します。

避けたい命名

  • /getUserList
  • /UserData/1
  • /users/1/delete
  • 動詞や大文字が混ざる
  • ルールがばらばら

おすすめの命名

  • /users
  • /users/1
  • /users/1/orders
  • 名詞・複数形・小文字
  • 区切りは一貫させる
31
13
API設計入門 - 設計

バージョン管理

APIは育っていきます。既存の利用者を壊さずに進化させるためにバージョンをつけます。

APIのバージョニング

APIの仕様を変えるとき、古い利用者を壊さないように版（バージョン）を分ける考え方。URLの先頭にv1のように付ける方法がよく使われる。

・/v1/users のようにURLに版を入れる

・仕様を大きく変えるときは v2 を用意

・旧版をしばらく残して移行期間を作る

・利用者が安心して使い続けられる

32
14
API設計入門 - 設計

復習 認証・認可

以前学んだ認証と認可は、API設計でも欠かせない要素です。

  • 認証は「誰か」を確かめること
  • 認可は「何ができるか」を決めること
  • APIキーやトークンで本人確認をする
  • 権限の無い操作は403で断る
  • 設計の段階で守り方を決めておく
33
15
API設計入門 - 設計

エンドポイントの構造

リソースは入れ子で表せます。usersの下に、その人の注文がぶら下がるイメージです。

/v1
/users
GET 一覧
POST 作成
/users/1 個別
/users/1/orders
GET その人の注文一覧
POST 注文を作成
/products
GET 商品一覧
GET /products/5 個別
34
16

API設計入門 - 実践

4

第4部 エラー設計とドキュメント

困らせない・伝わる設計

40
17
API設計入門 - 実践

エラー設計の例

・エラーも分かりやすく返すのが良い設計です。コードと一緒に、原因が分かる本文を返します。

json
{
  "error": {
    "code": "USER_NOT_FOUND",
    "message": "指定されたユーザーは存在しません",
    "status": 404
  }
}
41
18
API設計入門 - 実践

良いエラー設計の3点

エラーは利用者を助ける情報です。次の3点を満たすと親切なAPIになります。

正しいコード
  • 状況に合うステータス
  • 404と500を区別する
原因が分かる
  • 何が悪いか説明する
  • 次の行動が分かる
形が一定
  • エラーの形を統一
  • 利用側が扱いやすい
42
19
API設計入門 - 実践

ドキュメントの重要性

どんなに良い設計でも、使い方が伝わらなければ使われません。ドキュメントは設計の一部です。

APIドキュメント

APIの使い方を説明した資料。どのURLに、どのメソッドで、どんなデータを送ると、何が返るかをまとめたもの。利用者が迷わず使うための地図になる。

・各エンドポイントの説明をまとめる

・リクエストとレスポンスの例を載せる

・ステータスコードの意味を書く

・設計と一緒に育てていく

43
20
API設計入門 - 実践

設計の良し悪しと開発のしやすさ（イメージ）

一貫した設計とドキュメントがあると、利用側の理解にかかる時間が減る傾向です。あくまでイメージです。

15 理解にかかる時間(イメージ)129630
3理解にかかる時間(イメージ)
7理解にかかる時間(イメージ)
14理解にかかる時間(イメージ)
よく設計されたAPI
ふつうのAPI
ばらばらなAPI

出典: 設計の一貫性と理解しやすさの傾向を示す概念図（概算）

44
21
API設計入門 - 実践

良い例と悪い例

これまで学んだ原則を、最後に一枚で見比べます。違いを感じ取ってください。

悪い例

  • /getUser?id=1 のように動詞入り
  • 成功も失敗も200で返す
  • エラー本文が無い
  • バージョンが無い
  • 命名がばらばら

良い例

  • GET /v1/users/1 と名詞で表す
  • 状況に合うステータスを返す
  • 原因の分かるエラー本文
  • /v1 でバージョン管理
  • 命名が一貫している
45
22
API設計入門 - まとめ
クイズ

振り返りクイズ

今日の内容を確認しましょう。

RESTfulなAPIのURL設計として、最も望ましいものはどれ？

A
GET /getUserById?id=1
B
POST /deleteUser/1
C
GET /users/1
D
GET /v1/UserDelete?id=1
50
23
API設計入門 - まとめ
答え

振り返りクイズ 解答

RESTfulなAPIのURL設計として、最も望ましいものはどれ？

A
GET /getUserById?id=1
B
POST /deleteUser/1
C
GET /users/1
D
GET /v1/UserDelete?id=1

RESTではURLは名詞（リソース）だけにし、操作はメソッドで表すのが基本です。GET /users/1 は「usersリソースのうちIDが1のもの」を取得する正しい形です。動詞や操作名をURLに入れた他の選択肢は望ましくありません。

51
24
API設計入門 - まとめ

質疑・次回予告

今日のまとめと、次に学ぶテーマです。質問があればここで受け付けます。

今日のおさらい
  • URLは名詞、操作はメソッド
  • 状況に合うステータスを返す
  • バージョンとドキュメントで育てる
次回予告
  • ブロックチェーン 〜改ざんできない記録〜
  • つながる台帳のしくみを学ぶ
52
25
"

使いやすいAPIは「住所は名詞、動作はメソッド、結果は正しいコードで」。一貫したルールとドキュメントが、見ただけで使い方の分かる優しいAPIを作ります。

— API設計入門

53
26