Hatena::ブログ(Diary)

フリーフォーム フリークアウト Twitter

2013-01-21

Web API 設計のベストプラクティス集 "Web API Design - Crafting Interfaces that Developers Love"

| 22:59 |

f:id:cou929_la:20130120145130p:image

no title

Web API Design という本を読みました. Web API 設計のベストプラクティスがまとめられている, apigee という API のソリューションを提供している会社がだしているフリーの ebook です. コンパクトに 30 ページほどに読みやすくまとめられています.

以下要点のメモです.

開発者視点

  • API の目的はアプリケーション開発者 (API 利用者) が可能な限り成功すること. 開発者の視点で設計すること. 本書ではそのような API を実現する tips を紹介する.

Pragmatic REST

URL

  • 動詞ではなく名詞
    • リソースを名詞であらわす. Collection: `/dogs/`, Specific element: `/dogs/1234`
    • HTTP メソッドリソースの操作とする. POST は create, GET は read, PUT は update, DELETE は delete
  • 単数形よりも複数形をつかう
  • URL の階層を浅く保つ
    • リソースの関係を表したい場合. 例えばオーナー 5678 が飼っている犬をあらわす URL は `/owners/5678/dogs`
    • 目安として `/resource/identifier/resource` 以上に URL を深くすべきでない
    • URL は浅く保ち, 複雑さはクエリパラメーターに押しこむ

エラーハンドリング

例:

{
    "developerMessage": "開発者向けメッセージ",
    "userMessage": "ユーザ向けメッセージ. 必要に応じて",
    "errorCode": 1234,
    "moreInfo": "http://dev.example.com/errors/1234"
}

バージョニング

  • 必ずバージョンをつけること
  • v と整数のバージョン番号を URL のトップレベルにつける. e.g. `/v1/dogs`
    • バージョン番号にドット (マイナーバージョン) は不要. APIインタフェースであり実装ではない. マイナーバージョンは粒度が細かい.
  • バージョンは URL にいれるべきか, HTTP ヘッダにいれるべきか
    • ブラウザからの開発しやすさを考えて URL にバージョンをいれるべき
  • パラメータURL とヘッダどちらに入るかは次のルールにしたがう
    • API のレスポンスをハンドルするロジックが変わる場合, URL にいれる
    • そうでない場合 (例えば OAuth の情報) ヘッダに入れる

Partial response と Pagination

いずれも一部の必要なデータだけをクライアント側に返す戦略. Partial response は利用者が指定したフィールドだけを返す. Pagination は返す件数を制御する方法.

  • Partial response
    • `fields` パラメータにカンマ区切りで指定
    • e.g. `/dogs?fields=name,color,location`
  • Pagination

リソース操作ではない API のデザイン

  • 計算・翻訳・変換など, ドメインによってはリソース操作でない API も存在しうる
  • その場合名詞でなく動詞をつかう
    • e.g. `/convert?from=EUR&to=CNY&amount=100`
  • ドキュメントには特殊なケースだということを明記しておくこと

複数フォーマットのサポート

属性名

  • JavaScript の規約にあわせる
    • 先頭小文字のキャメルケース

例:

{"createdAt": 1320296464}

検索のための tips

  • 検索は複雑なクエリが想定されるので, Google にならって動詞URL にするのがよい
  • `/search?q=fluffy+fur`
  • 検索のスコープを絞る場合は search の前にスコープをつける
    • `/owners/5678/dogs?q=fluffy+fur`
  • 結果のフォーマットは拡張子ふうに指定
    • `/search.xml?q=fluffy+fur`

API リクエスト先をひとつの subdomain にまとめる

例外的な動作への tips

クライアントHTTP エラーコードをインターセプトする場合
  • たとえば FlashHTTP のエラーレスポンスを受け取ると, エンドユーザのアプリにエラーコードを表示する
  • これを避けるために `suppress_response_codes=true` というクエリパラメータを提供する
    • これが指定されていると HTTP レスポンスコードが常に 200 になるようにする
  • レスポンスボディは通常通りのエラーコードやメッセージを返す. クライアントアプリはこれを見てハンドリングする
限られた HTTP メソッドしかサポートしないクライアントへの対応
  • 例えば PUT, DELETE をサポートしないクライアントへの対応
  • `method` クエリパラメータで指定するようにする
    • `/dogs?method=post` (create), `/dogs` (read), `/dogs/1234?method=put&location=park` (update), `/dogs/1234?method=delete` (delete)

認証

Chatty APIs

  • Chatty API (おしゃべりな API, つまり情報が少なく何度も呼び出さないといけないもの) をいかに避けるか
  • まず RESTful に設計し, そのごショートカットを追加する
    • 複数の API 呼び出しを組み合わせないと実現できない使い方を, 一度の呼び出しで実現できる API を追加してあげる
    • 先にショートカットを作ってはいけない. まずは RESTful なデザインで, 必要に応じてショートカットを追加する
  • partial response にドット演算子を導入して, 別のリソースのフィールドを参照できるようにする
    • `/owners/5678?fields=name,dogs.name`

SDK

  • API がよく設計されドキュメントも整っていれば SDK は不要
  • 一方で API をつかうためにドメインの知識が必要な場合, SDK を提供するという手がある
  • API を改修するのではなく SDK を提供することで API をクリーンに保てるなどいくつかのメリットがある

API Facade Pattern

  • システムのフロント (API) とバックエンド (システム本体や DB など) のつなぎかた. Facade Pattern をつかう
  • フロントとバックエンドの間に抽象的なレイヤーを一枚はさむ
  • 設計のしかた
    1. まず理想的な API インタフェースを設計する
    2. stub を用意して上記のインタフェースを実装する
    3. facade と実際のシステムをつなぐ

参考