私的API設計メモ
この記事はKosen13s' Advent Calendar 2018の記事です．
アドカレは初めてで，何を書こうか悩んでいるのですが，最近API設計のお仕事が舞い込んできたので，インプットしたことをまとめようと思います．
参考にしたのはこちらの本です． 第3章まで読みました．
エンドポイントの設計とリクエストの形式
APIエンドポイントの考え方
そもそもエンドポイントとは
≒URIと考えてOK
エンドポイントの基本的な設計
APIのエンドポイント設計
URI（リソース）とアクションの組み合わせで決める
レスポンスデータの設計
データの内部構造の考え方
「フロントは一つの画面ごとに一つのAPIを叩く」ことを原則として考える．
一つの作業に対して一つのAPIを用意する．
エンベロープは必要か
ヘッダやレスポンスなど，全てのデータを同じ構造で包むこと
ほとんどの場合冗長なので必要ない，レスポンスだけ返そう
データはフラットにすべきか
こだわりがない限りフラットにすべき
配列とフォーマット
複数のデータを返すときは，配列をそのまま返すのではなく，オブジェクトを返そう
配列の件数，あるいは続きがあるかをどう返すべきか
必ずしも全件数を知る必要はない．
続きがあるよフラグを返すという解決策もあり
各データのフォーマット
各データの名前
スネークケースが良さげ
エラーの表現
ステータスコードでエラーを表現する
ぴったり合うエラーコードがあればそのエラーコードを選び，なければ400や500など，00番台のエラーコードを選ぼう．
エラーの詳細をクライアントに返す
エラー用JSONを返そう
errorという配列で表現すれば，複数のエラーを返せる
最後に
API設計に関しては，基礎知識を付けるだけでなく，TwitterやFacebookなど，広く公開されている有名なAPIを読み解き，なぜこのように設計したのかを考えながら使ってみることが大事ですね！
