WEB API DESIGN
GOOD PRACTICE

良いWEB API設計の実践

前置き

最近WEB APIの設計について
チーム内で話すことが多いので、WEB API DESIGN読んでました

  • 「実践的REST」クラスタにより書かれた30ページのPDF
  • オリジナルは全部英語だが全文日本語訳されたものが 某ブログで公開 されてる。ありがたや（-人-）
    • 30-60分で全部読めるので超おすすめ
  • 内容は割と素晴らしい

今日の目的


WEB API設計の一般的なgood practiceを共有し、
セクション内での意思決定のベースにする

※あくまでgood practiceであり、
盲目的に従うべきではないことに注意

本題の前に、
WEB API設計が重要な理由

  • 内部設計のまずさ→リファクタリングで修正可能
  • バグ→見つけたら直してデプロイでOK
  • WEB APIがまずくて修正→使用してる関係システムへ
    使い方を修正してくださいと頭を下げる必要あり


だからこそ、特に最初のAPI設計は
よく考えて行いましょう

やっと本題入ります

① ベースURLは名詞にしろ！

名詞であるURLに対して
動詞であるHTTPメソッドが
作用するのがHTTPの根幹

犬の情報を読み込む GET /dogs/1234
犬の情報を書き込む PUT /dogs/1234
犬の情報を削除する DELETE /dogs/1234

理想的にはURLは２種類まで突き詰めましょう
/dogs (コレクション)
/dogs/1234 (コレクション中の特定要素)

補足：
コレクションは
複数形 or 単数形？

最近のWebサービスのAPIでも２つに別れる
Foursquare: /checkins
GroupOn: /deals
Zappos: /Product

WEB API DESIGNでは複数形を推奨してるが、
最も優先されるべきは
システム全体でどちらかに統一されていること

② APIにバージョンをつけろ

バージョンは必須
API仕様の修正やシステム更新などが
圧倒的にしやすくなる

例
Twilio /2010-04-01/Accounts/
salesforce.com /services/data/v20.0/sobjects/Account
Facebook ?v=1.0
typical good practice
/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の属性名は
キャメルケースにしろ

Twitter "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文化だから
timing = JSON.parse(response).createdAt;

⑥ おしゃべり(chatty)なAPIを避けろ

10歳の犬を持つ飼い主の名前すべてを取得したい

/dogs?old=10&fields=owner_id １回
{ { owner_id: "324" }, { owner_id: "199" }, .... } 24人

/owner/324?fields=name /owner/199?fields=name ... 24回

= 計25回のAPI呼び出し

このように単純なことをしたいのに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呼び出しは２回で済む

最後に、最も大事なこと

⑦ Web企業が提供してる
WEB APIから学べ

何も見ずに設計したAPIより
twitter REST APIを参考にして設計したAPIのほうが
100倍いい

イケてるWEB企業が公開してるAPIには
先人たちの経験すべてが詰まってる

WEB API DESIGNでもほとんどのストーリーは
実在のAPIを例に出して展開

他のすべてのpracticeは忘れてもいいので、
この原則だけは忘れない（戒め）
Made with Slides.com