これは何
普段主にインフラエンジニアとして働いている私が、会社で初めてAPIを一つ書いたので、そこで得た学びや考えたことを記録しておこうと思います。
何を学んだこと・考えたこと
仕様書を書こう
どのようなAPIなのか、目的やリクエストパラメーターやレスポンスフォーマットについて定義する。 特にAPIの場合はレスポンスフォーマットが変わるとクライアント側でパースするのに困ってしまうのではっきり定義しなければならない。 APIは使う側ありき。
レスポンスフォーマットの統一性
他のAPIとできるだけ揃えた方が良い。統一性がないと使う時に大変。 ドメイン全体でJSONのうちのMeta情報やDataオブジェクトをどのようなフォーマットにするのかというのを決めておき、各種APIはそれに従うのが良い。何も決めずに走り出すとメチャメチャになってしまうのでまず共通ルール。共通ルールはフレームワークへ落とし込んでおいて、そのフォーマットから外れなければ簡単にレスポンスを作れるようにしておく。 共通ルールをしっかり作っておくと大枠は固定されるので、後から細かいところをちょっと変えるにしても混乱が少ない。
DBで保持しているデータとAPIのJSONのキー名は必ずしも合わせる必要がない
裏で使っている名前に引きずられがち。利用者にとって使いやすい名前にする。
例えばDBで公開状態をpublic_status
という名前で持っており、0,1の値を取るとする。どちらの値がpublicなのかちょっと分かりづらいと感じたとする。その場合、public_status
にこだわらなくても、APIレスポンスとしてはデータ要素が削除されているかというのが重要であるなら is_deleted
という名前で返してあげるのが親切。
時間はUnixTimeで返そう
JSTやUTCで帰っていると使いづらい。DBでJSTで保持していても変換してUnixTimeで返すと良い。
エラー応答についても定義しておこう
主なエラー応答やステータスは共通ルールとして定義しておこう。 各APIの仕様書においては、特殊な条件やちょっと迷いそうな場合についてエラー応答について記述しておこう。
仕様書はコードからすぐに参照できるように書いておこう
@see などで参照リンクとしておいておこう。 簡単な説明はコードにコメントしてしまった方が良いが、長くなるなら仕様書に切り出してリンクを貼っておくのを忘れずに。1セットで管理していく。
コードフォーマットはエディタに任せよう
エディタに微妙にフォーマット設定が入っていなくて細々としたPRコメントを沢山もらっしまった。 フォーマットについてはプロジェクトのREADMEにすべて明記して新しく入った人が迷わないようにする。可能であればエディタ設定ファイルなども共有しよう。 人間がやることではない。機械に任せられるのは機械に任せよう。
テストを書こう
PRコメントに長々と手動の動作確認の結果を書くのはよくない。TDDの考え方を取り入れて仕様が決まったら先にテストを書いてしまうのが良い。
コメント: とはいえ今回のケースでいうと、それなりにテスト書くのに苦労したので先に書くのは難しかったかも。Seleniumでテストを書いたのだが、他の開発者がMacだったが私だけWindowsでテストを回したので無駄に苦労した。開発環境は可能なかぎり教えてくれる人と合わせた方が良い。
同じような応答を返すWebFrontページがあるなら仕様を合わせよう
WebFrontページとソート順や件数などの仕様が異なると混乱を招く。仕様がくいちがうならその旨を理由と合わせて明記しよう。