ドキュメントの薄いAPIに繋ぐ
目標
ドキュメントが不十分な顧客企業のAPIに接続して、仕様にない事実まで全件調査で確認し、リトライまで処理できるようになります。
なぜ重要なのか
新しいAPIに接続するときの最初の作業は、コードを書くことではなく、全件調査です。すべてのページを1回回りながら、総件数、合計、各フィールドの欠損件数を数えてみます。この1回が、その後の数週間のデバッグをなくします。「全60件のうち6件はregionが空です。これらをどう処理しますか」を最初の週に尋ねれば、あとで地域別の合計が合わないという報告が来ません。
ページネーションで最もよくあるバグは、totalでページ数を計算しながら割り算の余りを忘れることです。最後のページがまるごと抜け、その事実は、合計がわずかに小さいという形でしか現れないので、発見が遅れます。そのため、ステップ4では、計算値を信じず、実際に回って数えて検証します。
リトライでは、対象の区別が重要です。5xxとネットワークエラーは一時的なことがあるのでリトライの対象ですが、4xxは、リクエストを直さない限り何度送っても同じ結果なので、リトライは負荷を上げるだけです。
API仕様(Wikiに書かれたすべて)
GET /health→{"status": "ok"}GET /meta→{"version", "page_size", "total"}GET /orders?page=N→{"page", "page_size", "total", "has_next", "items": [{id, customer, amount, region}]}。pageは1からGET /flaky→ ときどき失敗するとだけ書かれている
ステップ
/opt/app/api.pyを実行して、127.0.0.1:8002/healthが200を返すようにしてください。/metaのversionの値を、/root/api/version.txtに書いてください。- 全ページ数を計算して、
/root/api/pages.txtに書いてください。 - すべてのページを実際に回って収集したレコードの総数を、
/root/api/count.txtに書いてください。 - すべてのレコードの
amountの合計を、/root/api/sum.txtに書いてください。 regionが空文字列のレコード数を、/root/api/no_region.txtに書いてください。/flakyをリトライして、最終的に受け取れたステータスコードを、/root/api/flaky_ok.txtに書いてください。/root/api/report.mdに、バージョン、総件数、金額の合計をまとめてください。
参考
python3 /opt/app/api.py &で起動します。curl -s http://127.0.0.1:8002/orders?page=1 | python3 -m json.toolで、まず構造を見てください。- 繰り返し:
for p in $(seq 1 6); do curl -s "http://127.0.0.1:8002/orders?page=$p"; done - よくあるミス1: ステップ3で余りを切り捨てて、最後のページを落とすことです。
- よくあるミス2: ステップ4で、
/metaのtotalをそのまま写すことです。実際に回って数えることが、このステップの目的です。
注文APIを起動する
/opt/app/api.pyを実行して、127.0.0.1:8002/healthが200を返すようにしてください。
/opt/app/api.pyを実行すると、127.0.0.1:8002で待ち受けます。/healthで確認してください。
APIのバージョンを確認する
/metaのversionの値を/root/api/version.txtに書いてください。
/metaのレスポンスはJSONです。versionフィールドの値だけを取り出してください。jqやpython3を使うと楽です。
全ページ数を計算する
全ページ数を計算して/root/api/pages.txtに書いてください。
/metaのtotalとpage_sizeで計算します。余りがあれば、ページがもう1つあります。
全ページを回って件数を数える
すべてのページを実際に回って収集したレコードの総数を、/root/api/count.txtに書いてください。
実際にすべてのページを回って、itemsを数えてください。totalフィールドをそのまま写さず、検証することが要点です。
金額の合計を求める
すべてのレコードのamountの合計を/root/api/sum.txtに書いてください。
すべてのページのitemsから、amountを足します。
欠損レコードを数える
regionが空文字列のレコード数を/root/api/no_region.txtに書いてください。
ドキュメントにない欠損です。regionが空文字列のレコードが何件かを数えてください。
不安定なエンドポイントを通過する
/flakyをリトライして、最終的に受け取れたステータスコードを/root/api/flaky_ok.txtに書いてください。
/flakyは、最初の数回は503を返します。200が来るまでリトライして、最終的なステータスコードを書いてください。
連携結果の報告書を書く
/root/api/report.mdに、バージョン、総件数、金額の合計をまとめてください。
バージョン、総件数、金額の合計がすべて入っている必要があります。最初の週に顧客に送る文書だと考えてください。