Web API ~the good parts~を読んで

せっかく読んだのでまとめます。
自分が公開するAPIを開発するためだけでなく、サーバーとクライアント側に分れたプロダクトを開発する際にも応用できます。

この本を読んで学べる事

・どのようにwebAPIを開発するべきか
・クライアントとサーバーサイドどこでデータを区切るのか
・openでもclosedでも明確でわかりやすく汎用的なwebAPIを作る事が大事(言うは易し)

2章と3章が対になっている

1章　webAPIとは?

ここはイントロなので割愛

2章 エンドポイントの設計とリクエストの形式

良いエンドポイントとは

• 短いこと

• 読んで理解できる
  ☓ http://xxxxx.com/api/p0101/c0704/lawyer
  ↑何かの条件で絞り込まれた弁護士がとれそう？
  ○ http://xxxxx.com/api/lawyer/prefecture=1&category=4
  ↑県とカテゴリーの条件で絞り込まれた弁護士が取れると推測できる

• 大小小文字なし
  ☓　http://xxxxx.com/getLawyer
  　文字をつなぐ時はハイフンでつなぐ(googleが推奨)また、ディレクトリを切るとディレクトリを切る必要がなくなる。

• 改造しやすい
  ☓　https://xxxxx.com/c0500
  ○　https://xxxxx.com/api/cagegory/1
  1の数値を変えたら他のcategoryについての情報がとれそう

• サーバーのアーキテクチャーが反映されていない
  ☓　xxxx.com/cgi-bin/lawyer/1/pricings
  ↑サーバーのディレクトリ配置が推測できるためセキュリティーリスクにつながる
  ○　xxxx.com/lawyer/1/pricings

件数の取得位置が明確である

サービス名	取得数	相対位置	絶対位置
twiiter	count	cursor	max_id
youtube	maxResults	pageToken	publishBefore

などがあるが

筆者のおすすめは
page/per_pageまたはoffset/limitである。

• 統一されたルールで開発されている事が大事

memo

urlにsearchを入れる入れない問題
一覧を取得するのか検索結果を返すかによるのでサービスを意識すると良い

自社用のAPIを開発するならば、1ページに複数要素がある場合(トップページなど)パーツごとにAPIを作っていると何度も通信を発生させないといけないケースがあるので1リクエストに複数情報を入れるという手もある。

3章　レスポンスデータの設計

データ形式

海外サービスのほとんどがjson形式だが複数形式をサポートしないといけない場合は urlの後ろに?format=jsonみたいに指定できるようにするとgood

データはフラットにする

{
    id: 1,
    name : 'kousuke tanihata',
    profile :{
        gender : 'male'
    }
}

↑のように不要なネストを避ける

ページネーションをどのように表現するか

{
    profile : 
    {
        id: 1,
        name : 'kousuke tanihata',
    },
    {
        id: 2,
        name : 'j j',
    },
    hasNext : true,
}

エラーがある際はhttp statusを利用する

エラーがあった際はhttp statusをだけでなくにエラーの原因/要因を適切に伝える事が大事

{
    status : 404,
    error_message : 'idが指定されていません',
}

{
    status : 500,
    error_message : 'サーバーの不具合です。',
}

エラーの詳細を伝える

{
    'errors'[
        message : 'bad Auth data',
        url : 'doc.fshuh.com/fagahua',
    ]

}

↑誤ってhtmlを返さないように設計する
API使用者側がエラーを処理する難易度があがる(経験済み)

4章　　httpの仕様を利用する

番号代	意味
100	情報
200	成功
300	リダイレクト
400	ユーザー要因のエラー
300	サーバー要因のエラー

詳細↓
https://gist.github.com/rosylilly/3401612

上記のhttpメソッドを利用する事で getLawyerのようなurlを作成しなくすむ

200番台

202　Accepted ファイルアップロード中
204 No Content 削除完了

300番台

API設計では極力使わない
使うならドキュメントに書くようにする

400番台

405 httpメソッドが間違っている
406 フォーマットがエラー
409 Conflict リソースが競合している(指定されたIDやemailがすでに使用されている)
429 レートリミットを超えている

500番台

500　サーバエラー
504 一時的なエラー

リクエストを返す際には必ずメディアタイプを指定する

5章　設定変更をしやすいWeb APIを作る

urlを/v1　とか/v2で分けるのがオススメ(versionの区切りをメディアクエリーにすると冗長になる)
ドキュメントに廃止期間を明示する。

6章　堅牢なwebAPiを作る~安定性と安全性~

安全性

セキュリティー問題について
0,誤った設定で個人情報が公開された状態になっていたケースがある。
1,まずはhttps化しよう
2,xssに気をつける
json を返すならcontent-typeの値がtext/htmlではなく　Content-Type: application/jsonに設定する