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に設定する