Web API The Good Partsを読んで覚えておきたい所メモ

December 29, 2014

休日になったので以前から読みたいと思っていた、「Web API: The Good Parts」を一気に読んでみた。API初心者向けだと思う。内容は平易でよくまとまっていてわかりやすい。僕もちょっとだけAPIを書いたことはあるけれど、きちんとしたものを作った経験がないし、周辺の知識が欠けていると思って手にとって見たけれど、読み終わって思うのは読んでよかったなぁという感じ。

Web API: The Good Parts

気になったところを書き出してみる。自分のものになっていないものも多く含まれると思うけれど、書き出すことで一旦整理できれば。あとで検索できるようにページ数も書いておく。

気になった所メモ

感想も入ります。

ProgrammableWeb - p.8
- さまざまなAPIを集めてその情報を公開しているAPI
import.io, kimono - p.12
- ウェブページをAPIに変換するサービス
POSTで送信したデータは指定したURIに従属（subordinate）したものになる。 - p.31
- 例えば、https://api.example.com/v1/friendsにPOSTすると、https://api.example.com/v1/friends/12345が新たに生成されるイメージ。
- PUTはhttps://api.example.com/v1/friends/12345に対してその内容を書き換える。
- PUTは送信するデータでリソースを完全に上書きする。
- PATCHは一部だけを更新する
「1スクリーン1APIコール、1セーブ1APIコール」（『API Strategy and Practice』における『Michelle Titolo氏とPaul Wright氏の講演』） - p.60
- 一つの画面を表示するためにコールするのが1つのAPIですむようにそれに合わせたAPIを用意し、何らかのデータをサーバに保存する場合にも1回のコールですむようにそれ向けのAPIを用意するのが良いということ
- こういう風に考えていいんだと思った。目的に応じて複数コールするのか1つで済ませるのか迷ってたけど、こういう風に考えていいんだと思った。
1つの作業を完結するために複数回のアクセスを必要とするようなAPIの設計は”Chatty（おしゃべりな） API”と呼ばれる - p.76
- https://api.example.com/v1/users/12345?fields=name,ageというようにレスポンスの内容をユーザが選べるようにするのも手。FacebookのAPIもこんな感じだったな。
- レスポンスグループを作って、そのグループごとにまとまったフィールドを返すのも良い
JSONは配列で返さない方が良い - p.82
- JavaScriptとして正しい文法になっているとJSONインジェクションという攻撃を受ける
JSONではキャメルケースを使うのが良いとされている -p.86
- JSONがベースとしているJavaScriptの命名規約において、キャメルケースの利用がルール付けされているケースが多いから。
- Googleのスタイルガイド
性別データはgenderを使い、値をmaleやfemaleなどの文字列にするのが良さそう - p.88
日付はRFC3339を使うのが良さそう - p.89
エラーコードはステータスコードと区別するために4桁の数字にして、1000番台は汎用的なエラー、2000番台はユーザー情報のエラーというようにカテゴリ分けをすると便利かも - p.96
- エラーメッセージには開発者向けのメッセージを含めるのも良い
- エラーコードってどういう感じに振ればよいか曖昧だったので指針をもらった感じ。
HTTPSを使うことで、APIのやりとりの内容はもとより、エンドポイント、ヘッダに含められて送られるセッション情報などが暗号化される - p.159
- ただし、OpenSSLのバグ、SSL証明書の偽造などがあるので100％安全とはいえない
毎回のAPIアクセスの際にAPIの残りアクセス可能回数などをレスポンスに含めてクライアントに返す。ヘッダに格納するのが一般的 - p.194
- Apigeeや3SCALEなどがレートリミットの調整を簡単に行うための機能を提供している
ApigeeなどAPIコンソールを生成するサービスがある - p.200

参考にした本

Web API: The Good Parts