PublicAPIのエラーハンドリング / PublicAPI error handling

Transcript

1. PublicAPIのエラーハンドリング hyudai 2024年5⽉31⽇
2. 2 hyudai
 2022年9月〜API基盤チーム
 2023年7月〜外部連携サービス部 クレジットカードとの連携や同期体 験改善に従事
 外部連携サービス部エンジニア
3. 　 コスパよくPublicAPIを運⽤したい
4. 　 PublicAPIの定義 運⽤負荷の低いPublicAPIを提供する エラーにおけるセキュリティ ⽬次
5. 　 (この登壇における)PublicAPIの定義 会社外に向けて発信するAPI全般 PublicAPIに該当するもの
6. 　 (この登壇における)PublicAPIの定義 会社外に向けて発信するAPI全般 PublicAPIに該当するもの • freee会計などの不特定多数に向けて提供されるAPI freee Developers Community https://developer.freee.co.jp/
7. 　 (この登壇における)PublicAPIの定義 会社外に向けて発信するAPI全般 PublicAPIに該当するもの • freee会計などの不特定多数に向けて提供されるAPI • ⼀般公開していないが、外部の企業との通信に使⽤するAPI
8. 　 (この登壇における)PublicAPIの定義 PublicAPIに該当しないもの
9. 　 (この登壇における)PublicAPIの定義 PublicAPIに該当しないもの • ⾃社内での利⽤のみを想定した通信 ◦ private API ◦ マイクロサービス間の通信 • プログラム間の通信以外の⽬的で作られたもの ◦ UIを提供するHTML
10. 　 PublicAPIに該当するもの • freee会計などの不特定多数に向けて提供されるAPI • ⼀般公開していないが、外部の企業との通信に使⽤するAPI PublicAPIに該当しないもの • ⾃社内での利⽤のみを想定した通信 ◦ private API ◦ マイクロサービス間の通信 • プログラム間の通信以外の⽬的で作られたもの ◦ UIを提供するHTML
11. 　 ⼀般公開されていないAPIをPublicAPIに含める理由 コミュニケーションコストが無視できない
12. 　 ⼀般公開されていないAPIをPublicAPIに含める理由 コミュニケーションコストが無視できない 社内の場合 • 問題が発⽣した時にslackなどのツールですぐに連絡を取れる • 内部だからこそ機密情報を使ったやりとりができる ◦ このAPIは N + 1が潜んでいるのであんまり叩かないで欲しいなど
13. 　 ⼀般公開されていないAPIをPublicAPIに含める理由 コミュニケーションコストが無視できない 社外の場合 • mailでのやり取りになる ◦ ビジネス⽂書に慣れていない場合は内部レビューが⼊ることも • 機密情報を伝えることは難しいので情報伝達の粒度が荒くなる ◦ 粒度が荒くなるのに正確性を要求される • 連絡を送ったとしても返信がいつになるのかわからない ◦ 返信が1,2週間遅れることも...
14. 　 ⼀般公開されていないAPIをPublicAPIに含める理由 コミュニケーションコストが無視できない 問い合わせ時の対応について API利⽤者側 ◦ 社内である程度調べ上げて確からしいという仮説が⽴った状態 ◦ 調べ上げた結果何にもわからなかった時... API提供者側 ◦ 精度の⾼い状態で返信を送らなければならない ◦ アクセスログとかまで⾒に⾏く必要があるかもしれない
15. 　 ⼀般公開されていないAPIをPublicAPIに含める理由 この問題は⼀般公開されているAPIであっても同じですよね？
16. 　 運⽤負荷の低いPublicAPIを提供する ユーザーに⾃⼰解決をしてもらうことが重要 • エラーを充実させる • チュートリアルを含めたドキュメントの整備 ◦ 最初にAPIを叩くまでの時間が⼀番挫折しやすい(IMO) • SDKやライブラリを提供する
17. 　 運⽤負荷の低いPublicAPIを提供する ユーザーに⾃⼰解決をしてもらうことが重要 • エラーを充実させる • チュートリアルを含めたドキュメントの整備 ◦ 最初にAPIを叩くまでの時間が⼀番挫折しやすい(IMO) • SDKやライブラリを提供する
18. 　 運⽤負荷の低いPublicAPIを提供する エラーを充実させる 問題の特定 • ステータスを充実させることで提供者と利⽤者のどちらに問題があるの かを明確にする • 状況に合わせた対応策を提⽰ • ステータスコード200,400,500をちゃんと使い分けることが⼤事
19. 　 運⽤負荷の低いPublicAPIを提供する エラーを充実させる 問題の特定 • ステータスを充実させることで提供者と利⽤者のどちらに問題があるの かを明確にする • 状況に合わせた対応策を提⽰ • ステータスコード200,400,500をちゃんと使い分けることが⼤事 問題が発⽣した際のユーザーのアクションを案内 • ⼊⼒データ形式をXYZに修正してください • rate limitです
20. 　 もしエラーが整備されていないAPIだと？ APIの仕様 常に200okでレスポンスされるAPI 成功しても失敗しても200、⼆つの違いはresponseのみ シナリオ 会計ソフトに登録している固定資産の数を調べたくてindexのAPIを叩いた ら200okで返ってきた！ただしbodyは空っぽ この時のデータは次のうちどちらの解釈をすればいい？ • 本当に固定資産が何もない時 • ⼊⼒値が間違えてエラーになった時
21. 　 もしエラーが整備されていないAPIだと？ APIの仕様 成功すると200, 失敗すると500が返ってくる。 エラーメッセージは常に「エラーが発⽣しました」 シナリオ すでに運⽤に乗っているサービスで、とある会社との通信に使⽤している APIが急に500エラーを返してきた。
22. 　 もしエラーが整備されていないAPIだと？ シナリオ すでに運⽤に乗っているサービスで、とある会社との通信に使⽤している APIが急に500エラーを返してきた。 まずどっちの問題...? • 先⽅のサーバーが落ちた？ • リクエストの形式が不正...?でも今まで動いてたし...
23. 　 もしエラーが整備されていないAPIだと？ シナリオ すでに運⽤に乗っているサービスで、とある会社との通信に使⽤している APIが急に500エラーを返してきた。 調査に難航したため問い合わせをしたところ • 「実装時からリクエストの形式が不正だったが、内部でvalidationする ようにした」 ◦ 利⽤者側: 先⽅の都合はわからない ◦ 提供者側: バグを修正したら問い合わせが増えた... どちらも幸せにならない結末になるかもしれません
24. 　 もしエラーが整備されていないAPIだと？ 先ほど例に出したAPIはフィクションです。 ただ、エラーメッセージがないと⾏える調査にも限界があります。2つ⽬に紹介 したものはどちらかというとAPI利⽤者側の実装ミス起因ですが、それすらも⾃ ⼰解決することは難しいです。 不適切なエラーを提供しているAPIは結果として⾃らの保守運⽤コストが犠牲に なります。
25. 　 エラーにおけるセキュリティ エラーを整備する壁は⼤きく分けて2つ • 内部のエラーとは異なる • セキュリティ
26. 　 エラーにおけるセキュリティ PublicAPIのみを提供しているサービスは少ない ⼤体は⼤元のサービスから切り出して、PublicAPI「でも」使えるように している 内部のエラーを流⽤している結果、ユーザーフレンドリーじゃないものが 出来上がる可能性も • PublicAPIを使うのは職業エンジニアだけではない • そもそも内部のエラーは⾒られていい状態になってますか？
27. 　 エラーにおけるセキュリティ エラーを詳細に書きすぎるリスク • 内部情報の漏洩 ◦ 現在のCPU使⽤率が80% overなので使⽤をやめてください • セキュリティレベルが極めて⾼い情報を出してしまった では何を返せばいいの？
28. 　 エラーにおけるセキュリティ ユーザーに何をして欲しいのかを明確にすることが大事
 
 freee会計のAPIでcompany_idを不正なパラメータの時の例
 
 {
 "message": "この事業所にアクセスする権限がありません",
 "code": "invalid_authorization_company_id"
 }
 
 何を確認すればいいのかはわかりますよね？
 ただし情報漏洩には気をつけてください
29. 　 終わりに コスパ良いPublicAPIの提供を⾏うために気を付けること • エラーの原因が提供者か利⽤者のどちらにあるかわかりますか？ • エラーのメッセージはユーザーのアクションにつながりますか？ • そのエラーはユーザーアクションに不必要な情報はだしてないですか？