WEB API DESIGN
GOOD PRACTICE
良いWEB API設計の実践
前置き
最近WEB APIの設計について
チーム内で話すことが多いので、WEB API DESIGN読んでました
今日の目的
WEB API設計の一般的なgood practiceを共有し、
セクション内での意思決定のベースにする
セクション内での意思決定のベースにする
※あくまでgood practiceであり、
盲目的に従うべきではないことに注意
盲目的に従うべきではないことに注意
本題の前に、
WEB API設計が重要な理由
- 内部設計のまずさ→リファクタリングで修正可能
- バグ→見つけたら直してデプロイでOK
- WEB APIがまずくて修正→使用してる関係システムへ
使い方を修正してくださいと頭を下げる必要あり
だからこそ、特に最初のAPI設計は
よく考えて行いましょう
よく考えて行いましょう
やっと本題入ります
① ベースURLは名詞にしろ!
名詞であるURLに対して
動詞であるHTTPメソッドが
作用するのがHTTPの根幹
作用するのがHTTPの根幹
犬の情報を読み込む GET /dogs/1234
犬の情報を書き込む PUT /dogs/1234
犬の情報を削除する DELETE /dogs/1234
理想的にはURLは2種類まで突き詰めましょう
/dogs (コレクション)
/dogs/1234 (コレクション中の特定要素)
補足:
コレクションは
複数形 or 単数形?
最近のWebサービスのAPIでも2つに別れる
Foursquare: /checkins
GroupOn: /deals
Zappos: /Product
WEB API DESIGNでは複数形を推奨してるが、
最も優先されるべきは
システム全体でどちらかに統一されていること
② APIにバージョンをつけろ
バージョンは必須
API仕様の修正やシステム更新などが
圧倒的にしやすくなる
圧倒的にしやすくなる
例
typical good practice
Twilio /2010-04-01/Accounts/ salesforce.com /services/data/v20.0/sobjects/Account ?v=1.0
/v1/devices/1234
version付加の手段: ①パス ②パラメータ ③ヘッダ
③ レスポンスにはJSONを使え
JSON: WEB APIフォーマットのデファクトスタンダード
XMLに比べて単純、単純なことは何より素晴らしい
④ レスポンスを部分的に
返せるようにしろ
/dogs/1234 | → | { age: 14, name: "coco", kind: "Maltese" } |
/dogs/1234? fields=name |
→ | { name: "coco" } |
WEB APIの主要なオーバーヘッドはレスポンスデータの量
すべてのAPIはfieldsパラメータを持つべき
必要な箇所ではページネーションも
⑤ responseの属性名は
キャメルケースにしろ
"created_at": "Thu Nov 03 05:19;38 +0000 2011": Bing "DateTime": "2011-10-29T09:35:00Z" Foursquare "createdAt": 1320296464
good practice: camelCase
なぜなら現在ブラウザで唯一実行できる言語JavaScriptが
camelCase文化だから
camelCase文化だから
timing = JSON.parse(response).createdAt;
⑥ おしゃべり(chatty)なAPIを避けろ
10歳の犬を持つ飼い主の名前すべてを取得したい
/dogs?old=10&fields=owner_id 1回
{ { owner_id: "324" }, { owner_id: "199" }, .... } 24人
/owner/324?fields=name /owner/199?fields=name ... 24回
= 計25回のAPI呼び出し
このように単純なことをしたいのにAPI呼び出しが膨大になる
= Chatty API
= Chatty API
⑥ おしゃべり(CHATTY)なAPIを避けろ
しかし、このミクロなAPIはRESTの本質でもある
じゃあどうするか?
あくまでREST APIをベースに、
それをショートカットする手段を提供する
それをショートカットする手段を提供する
10歳の犬を持つ飼い主の名前すべてを取得したい
/owner?fields=name&dog.age=10
ただし、決してショートカットAPIだけを
提供してはいけない(戒め)
提供してはいけない(戒め)
Chatty APIを避ける別の手法
IDを複数取れるようにする
10歳の犬を持つ飼い主の名前すべてを取得したい
/dogs?old=10&fields=owner_id
/owner/324,199,.....,231?fields=name
API呼び出しは2回で済む
最後に、最も大事なこと
⑦ Web企業が提供してる
WEB APIから学べ
イケてるWEB企業が公開してるAPIには
先人たちの経験すべてが詰まってる
先人たちの経験すべてが詰まってる
WEB API DESIGNでもほとんどのストーリーは
実在のAPIを例に出して展開
実在のAPIを例に出して展開
他のすべてのpracticeは忘れてもいいので、
この原則だけは忘れない(戒め)
この原則だけは忘れない(戒め)
WEB API DESIGN GOOD PRACTICE 良いWEB API設計の実践
WEB API DESIGN GOOD PRACTICE
By kbigwheel
WEB API DESIGN GOOD PRACTICE
WEB API DESIGNを読んだので、その中のpractice紹介に交えて自分の知る他のpracticeも紹介
- 6,412