cream

code rules everything around me

目視でAPIレスポンスを確認している

JSON APIを実装する仕事を最近はよくしています。

普段 Rails で開発していて、モバイルアプリ向けにいわゆるフツウにJSONで返す Web API を実装しています。

URLやインターフェースを設計して、それに合わせて rspec でテストを書いて中身を実装する流れで開発することが多い。

今回は、実装するときにテストを書くだけでなく、必ず 目視で APIのレスポンスをチェックするようにしてから、バグやミスが減ったということを紹介したい。*1

目視で確認する

たとえば、レストランのメニューを表示するようなAPIを作ってるとして、rspec (reques spec) を書いたとする。

describe 'GET /menu/:id' do
  let(:menu) { create(:menu) }
  subject(:submit_request) { get "/menu/#{menu.id}", headers: headers }

  it 'returns a menu' do
    expect(json).to match(
      hash_including(id: menu.id, ...)
    )
  end
end

テストを書いたら実行するわけだけど、書いたテストが通ることを確認するだけでなく、 APIリクエスト / レスポンスの中身がログとして実行時に出力されるようにしている。

新しく書いたテストだけでなく、既存のテストを実行するときにも、出力されて見えるようにしておく。

❯ bin/rspec spec/requests/api/menus_spec.rb
.
GET http://api.lvh.me/menus/bf28a586-d30c-4c1d-b812-e80415342d09
{}

{
  "id": "bf28a586-d30c-4c1d-b812-e80415342d09",
  "name": "ディナー1",
  "status": "published",
  "created_at": "2021-04-28T21:55:10+09:00",
  ...
}

中身をログに流しておいて、ざっと眺められるようにしておくと、実装時に色々な問題に気づきやすくなる。たとえば:

  • テストは通ってるが、バグのある部分があることに気づく
  • テストすべき挙動がテストされてなくて、テストが足りていないことに気づく
  • 表示してはいけないAPIフィールド (極端な例: IPアドレスなど) が含まれていることに気づく
  • ほかの既存APIのバグにたまたま気づく
    • null になっていてはいけないフィールドに null が入ってるなど

上のは簡単な例だけど、実際にはネストした構造のデータが出力されることが多い。

ネストしたデータはテストで比較的検証しにくく、バグも発生しやすいので、目視で検知する方法が役に立つ。

{
  "id": "bf28a586-d30c-4c1d-b812-e80415342d09",
  "name": "ディナー1",
  "menu_pages": [
    {
      "id": "xxx",
      "name": "ページ1",
      "product": {
        "id": "yyy",
        "name": "商品1",
        ...
      },
      ...
    }
  ] 
  ...
}

実装中は無意識に眺めているような感じで、実装が完成したら確認の意味でスクロールしてざっと見てみるようにしている。

流れるログを無意識に眺めているだけでも野生の勘が働いて、重大な問題に気づけることもあった。

rspec を実行時に自動でAPIレスポンスの中身を表示するコードは個人的に便利に使ってるので、gem として切り出している。見やすいように構造を整形したり、色を付けて表示したりする。

github.com

APIドキュメントの代わりにコピペする

一緒に働いているメンバーは優秀で、APIの仕様を細かく書かなくても理解してくれるので、代わりに簡単に説明を pull request に貼るようにしている。

そのときに、上で出力されたテキストを pull request にコピペしている。API の path やリクエストも含めて表示されるので、ざっと概要を伝えるのに便利。

たとえば、メニューを更新するようなAPIだとこんな例を貼っておくと、だいたい使い方は分かると思う。

PATCH http://api.lvh.me/menus/aa8d8277-43d3-47d0-bf04-655006ab27db
{
  "status": "unpublished"
}

{
  "id": "aa8d8277-43d3-47d0-bf04-655006ab27db",
  "name": "ディナー28",
  "status": "unpublished",
  "created_at": "2021-04-28T21:48:07+09:00",
...
}

まとめ

JSON API を実装するときに、レスポンスの中身を出力して目で見て確認するようにしているという話でした。

かなり単純な仕組みだけど、バグやミスに気づけることが増えた上に、ドキュメントを書きやすくなったので、プロダクトの品質を高めるのに役に立っている。

github.com

*1:割と単純な話なので、もしかしたら僕が知らなかっただけで皆は当然のようにやっている話なのかもしれない。