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は忘れてもいいので、
この原則だけは忘れない（戒め）

WEB API DESIGN GOOD PRACTICE

By kbigwheel

Made with Slides.com

WEB API DESIGN GOOD PRACTICE

WEB API DESIGNを読んだので、その中のpractice紹介に交えて自分の知る他のpracticeも紹介

  • 6,178

More from kbigwheel