Web API The Good Parts読んだメモ1

March 7, 2015

アプリ開発を想定してメモです。

決める際の大前提

  • 仕様が決まっているものに関しては仕様に従う
  • 仕様が存在していないものに関してはデファクトスタンダードに従う

エンドポイントについて

  • URIは基本は小文字に統一し、大文字小文字が違ったら404を返す

  • 基本1ページ1エンドポイントでいいのではないか?

    1つの作業を完結するために複数回のアクセスを必要とするようなAPIの設計は“Chatty(おしゃべりな)API”と呼ばれます。ChattyなAPIはネットワークのトラフィックを増加させ、クライアントの処理の手間を増やし、利用者にあなたのAPIがなんだか面倒くさい仕様であるという印象を抱かせます。つまり言い換えると良いことは何もないので、そのAPIがどのように使われるかをしっかりと想像し、少しでも利用しやすいAPI設計を心がけましょう。

レスポンスについて

レスポンスの内容を利用者が選べるようにするか

  • フィールド指定
  • レスポンスグループ
    • あらかじめフィールドのまとまりを用意しておく
    • Amazonはこの方式

エンベロープを使うかどうか

{
	"header" : {
		"status" : 200,
		...
	},
	response : {
		...
	}
}
  • この方式は使わずにHTTPのレスポンスヘッダに乗せる方がベターと筆者は言っている.

    上記の例におけるheader内に書かれていたようなメタ情報は、HTTPの仕様に則ってHTTPのレスポンスヘッダを使って書くことができます。そうするとHTTPのレスポンスボディは実際のデータのみを返すようにできるので、無駄を省くことができますし、レスポンスヘッダの書き方を全APIで共通にすれば、クライアント側のAPIアクセスも容易に抽象化することができます。

不要な階層化はしない

  • Googleのstyle guideに書いてある
  • 複数項目をまとめるだけの階層化は不要
  • 同じ構造を持つものが複数出てくるなら階層化

トップレベルは配列ではなくオブジェクトにする

・レスポンスデータが何を示しているものかがわかりやすくなる

・レスポンスデータをオブジェクトに統一することができる

・セキュリティ上のリスクを避けることができる

  • JSONインジェクション対策が大きい

命名規則について

  • スネーク/キャメル
    • javascriptのstyle的にはキャメル、Googleもキャメル
    • スネークのほうが読みやすいという研究結果もある?
    • Twitterとかはスネーク
    • 決めの問題
  • 単数、複数
    • 配列なら複数系

日付フォーマットについて

  • RFC 3339 が標準的でいいのでは

    • 2015-11-02T13:00:12+00:00
    • 2015-11-02T13:00:12Z

    RFC 3339を使うのがよいでしょう。理由としてはこのフォーマットが、数あるこれまでの日時を表すフォーマットの問題を解決し、読みやすく使いやすいものを目指してインターネット上で用いる標準形式として決められたものだからです。

  • タイムゾーン情報はアプリの設定を使う、とかならタイムスタンプでもいいかも?

    なおAPIを利用するクライアントが自社のスマートフォンアプリだけであるなど、あらかじめ予測可能であるばあい、RFC 3339ではなくUnixタイムスタンプを利用するという手も考えられます。Unixタイムスタンプはデータ形式としては単なる数値なので、比較や保持が非常に容易でサイズも小さくてすみ、使いやすいからです。ただしUnixタイムスタンプを使った場合は、ぱっとデータを見て時間が直感的にわかりづらくなるという問題があるため、開発時やデバッグの際にはやや手間が増えてしまいます。

エラーレスポンス

  • HTTPステータスをしっかりする
    • 200でエラーメッセージ返さない
    • 400/500
  • エラーメッセージをどこにいれるか
    • HTTPのヘッダーに入れたい
    • が、扱いやすさからBODYにいれることが多い
  • バリデーションエラーなどを扱う場合を考慮して、配列で返すと便利
  • 開発者向けとユーザ向けの二つのエラーを返すと便利
  • 問題発生時にエラーページhtmlにならないように

  • メンテ中ならRetry-Afterを設定しとくとよい

参考になるサイト

このエントリーをはてなブックマークに追加