読書メモ Web API The Good Parts

目的

業務のアプリ開発の一環でWebAPIの仕様を考えることがあり、仕様についてチームメンバー同士でなかなか合意に至らないことがある。合意に至らない原因はそれぞれに理想のAPI像があるためで、学習するよりも過去の経験や既存設計の延長線上の会話で議論する結果収束しない、みたいな感じ。

以前所属していた会社のAPIの設計が割とフロントエンドに優しい仕様になっていたこともあり、自分はどちらかと言うとフロントエンドがjson色付け係になれる方向で設計しがち。一方バックエンドの人は、BFFがない場合に過度にフロントエンドの仕様に寄せた設計にするのを避ける傾向がありそうで、両者ともに間違ったことを言っているとも思えなかったので自身を持って会話をできなかった。

最近いくつかAPIに関する技術書の存在を知り、その中でも一番評判の良かった本を読んでみた

感想とか

有名サービスのAPIを比較しながら良いWebAPIとはなにか?に答えている。

発行時期の関係で情報は少し古い気がする(初版が2014年)が、jsonをベースとしたAPIはそれほど大きなパラダイムが起こってなさそうだし公開してから頻繁に変えるようなものでもないので、気にしなくて良さそう。例示されたサービスの現状を見て、生き残っている仕様は長続きする仕様みたいな判断もアリだと思う。

APIをどういう単位で作成すべきか、それでどういうものを返却すべきかについて学ぶことができた。HTTPやAuthに関する情報はバックエンドの人に任せようと思っているので飛ばして読んだ。自分の中で一つ指針ができたので、今後迷うことがあればまずはこの本で学んだ原則に従って検討を進めようと思う

  • LSUDsとSSKDs
  • 覚えやすく、理解しやすいURI
  • ページネーションのAPIはデータ量が増えると相対位置指定だとパフォーマンスが落ちるので注意
  • REST LEVEL3 HETEOASの概念
  • メタ情報はbodyではなくheaderに。HTTPを活かす
  • 配列を直接返却するとセキュリティリスクがある。オブジェクトで包んだほうが良い
  • 時刻情報は特定言語の情報が含まれないRFC3339か、特定アプリのみで利用する場合は使いやすいUNIXタイムスタンプがおすすめ