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

by freee

Slide 1

Slide 1 text

PublicAPIのエラーハンドリング hyudai 2024年5⽉31⽇

Slide 2

Slide 2 text

2 hyudai  2022年9月〜API基盤チーム  2023年7月〜外部連携サービス部クレジットカードとの連携や同期体験改善に従事  外部連携サービス部エンジニア

Slide 3

Slide 3 text

　コスパよくPublicAPIを運⽤したい

Slide 4

Slide 4 text

　 PublicAPIの定義運⽤負荷の低いPublicAPIを提供するエラーにおけるセキュリティ⽬次

Slide 5

Slide 5 text

　 (この登壇における)PublicAPIの定義会社外に向けて発信するAPI全般 PublicAPIに該当するもの

Slide 6

Slide 6 text

　 (この登壇における)PublicAPIの定義会社外に向けて発信するAPI全般 PublicAPIに該当するもの ● freee会計などの不特定多数に向けて提供されるAPI freee Developers Community https://developer.freee.co.jp/

Slide 7

Slide 7 text

　 (この登壇における)PublicAPIの定義会社外に向けて発信するAPI全般 PublicAPIに該当するもの ● freee会計などの不特定多数に向けて提供されるAPI ● ⼀般公開していないが、外部の企業との通信に使⽤するAPI

Slide 8

Slide 8 text

　 (この登壇における)PublicAPIの定義 PublicAPIに該当しないもの

Slide 9

Slide 9 text

　 (この登壇における)PublicAPIの定義 PublicAPIに該当しないもの ● ⾃社内での利⽤のみを想定した通信 ○ private API ○ マイクロサービス間の通信 ● プログラム間の通信以外の⽬的で作られたもの ○ UIを提供するHTML

Slide 10

Slide 10 text

　 PublicAPIに該当するもの ● freee会計などの不特定多数に向けて提供されるAPI ● ⼀般公開していないが、外部の企業との通信に使⽤するAPI PublicAPIに該当しないもの ● ⾃社内での利⽤のみを想定した通信 ○ private API ○ マイクロサービス間の通信 ● プログラム間の通信以外の⽬的で作られたもの ○ UIを提供するHTML

Slide 11

Slide 11 text

　⼀般公開されていないAPIをPublicAPIに含める理由コミュニケーションコストが無視できない

Slide 12

Slide 12 text

　⼀般公開されていないAPIをPublicAPIに含める理由コミュニケーションコストが無視できない社内の場合 ● 問題が発⽣した時にslackなどのツールですぐに連絡を取れる ● 内部だからこそ機密情報を使ったやりとりができる ○ このAPIは N + 1が潜んでいるのであんまり叩かないで欲しいなど

Slide 13

Slide 13 text

　⼀般公開されていないAPIをPublicAPIに含める理由コミュニケーションコストが無視できない社外の場合 ● mailでのやり取りになる ○ ビジネス⽂書に慣れていない場合は内部レビューが⼊ることも ● 機密情報を伝えることは難しいので情報伝達の粒度が荒くなる ○ 粒度が荒くなるのに正確性を要求される ● 連絡を送ったとしても返信がいつになるのかわからない ○ 返信が1,2週間遅れることも...

Slide 14

Slide 14 text

　⼀般公開されていないAPIをPublicAPIに含める理由コミュニケーションコストが無視できない問い合わせ時の対応について API利⽤者側 ○ 社内である程度調べ上げて確からしいという仮説が⽴った状態 ○ 調べ上げた結果何にもわからなかった時... API提供者側 ○ 精度の⾼い状態で返信を送らなければならない ○ アクセスログとかまで⾒に⾏く必要があるかもしれない

Slide 15

Slide 15 text

　⼀般公開されていないAPIをPublicAPIに含める理由この問題は⼀般公開されているAPIであっても同じですよね？

Slide 16

Slide 16 text

　運⽤負荷の低いPublicAPIを提供するユーザーに⾃⼰解決をしてもらうことが重要 ● エラーを充実させる ● チュートリアルを含めたドキュメントの整備 ○ 最初にAPIを叩くまでの時間が⼀番挫折しやすい(IMO) ● SDKやライブラリを提供する

Slide 17

Slide 17 text

Slide 18

Slide 18 text

　運⽤負荷の低いPublicAPIを提供するエラーを充実させる問題の特定 ● ステータスを充実させることで提供者と利⽤者のどちらに問題があるのかを明確にする ● 状況に合わせた対応策を提⽰ ● ステータスコード200,400,500をちゃんと使い分けることが⼤事

Slide 19

Slide 19 text

　運⽤負荷の低いPublicAPIを提供するエラーを充実させる問題の特定 ● ステータスを充実させることで提供者と利⽤者のどちらに問題があるのかを明確にする ● 状況に合わせた対応策を提⽰ ● ステータスコード200,400,500をちゃんと使い分けることが⼤事問題が発⽣した際のユーザーのアクションを案内 ● ⼊⼒データ形式をXYZに修正してください ● rate limitです

Slide 20

Slide 20 text

　もしエラーが整備されていないAPIだと？ APIの仕様常に200okでレスポンスされるAPI 成功しても失敗しても200、⼆つの違いはresponseのみシナリオ会計ソフトに登録している固定資産の数を調べたくてindexのAPIを叩いたら200okで返ってきた！ただしbodyは空っぽこの時のデータは次のうちどちらの解釈をすればいい？ ● 本当に固定資産が何もない時 ● ⼊⼒値が間違えてエラーになった時

Slide 21

Slide 21 text

　もしエラーが整備されていないAPIだと？ APIの仕様成功すると200, 失敗すると500が返ってくる。エラーメッセージは常に「エラーが発⽣しました」シナリオすでに運⽤に乗っているサービスで、とある会社との通信に使⽤している APIが急に500エラーを返してきた。

Slide 22

Slide 22 text

　もしエラーが整備されていないAPIだと？シナリオすでに運⽤に乗っているサービスで、とある会社との通信に使⽤している APIが急に500エラーを返してきた。まずどっちの問題...? ● 先⽅のサーバーが落ちた？ ● リクエストの形式が不正...?でも今まで動いてたし...

Slide 23

Slide 23 text

　もしエラーが整備されていないAPIだと？シナリオすでに運⽤に乗っているサービスで、とある会社との通信に使⽤している APIが急に500エラーを返してきた。調査に難航したため問い合わせをしたところ ● 「実装時からリクエストの形式が不正だったが、内部でvalidationするようにした」 ○ 利⽤者側: 先⽅の都合はわからない ○ 提供者側: バグを修正したら問い合わせが増えた... どちらも幸せにならない結末になるかもしれません

Slide 24

Slide 24 text

　もしエラーが整備されていないAPIだと？先ほど例に出したAPIはフィクションです。ただ、エラーメッセージがないと⾏える調査にも限界があります。2つ⽬に紹介したものはどちらかというとAPI利⽤者側の実装ミス起因ですが、それすらも⾃⼰解決することは難しいです。不適切なエラーを提供しているAPIは結果として⾃らの保守運⽤コストが犠牲になります。

Slide 25

Slide 25 text

　エラーにおけるセキュリティエラーを整備する壁は⼤きく分けて2つ ● 内部のエラーとは異なる ● セキュリティ

Slide 26

Slide 26 text

　エラーにおけるセキュリティ PublicAPIのみを提供しているサービスは少ない⼤体は⼤元のサービスから切り出して、PublicAPI「でも」使えるようにしている内部のエラーを流⽤している結果、ユーザーフレンドリーじゃないものが出来上がる可能性も ● PublicAPIを使うのは職業エンジニアだけではない ● そもそも内部のエラーは⾒られていい状態になってますか？

Slide 27

Slide 27 text

　エラーにおけるセキュリティエラーを詳細に書きすぎるリスク ● 内部情報の漏洩 ○ 現在のCPU使⽤率が80% overなので使⽤をやめてください ● セキュリティレベルが極めて⾼い情報を出してしまったでは何を返せばいいの？

Slide 28

Slide 28 text

　エラーにおけるセキュリティユーザーに何をして欲しいのかを明確にすることが大事    freee会計のAPIでcompany_idを不正なパラメータの時の例    {  "message": "この事業所にアクセスする権限がありません",  "code": "invalid_authorization_company_id"  }    何を確認すればいいのかはわかりますよね？  ただし情報漏洩には気をつけてください

Slide 29

Slide 29 text

　終わりにコスパ良いPublicAPIの提供を⾏うために気を付けること ● エラーの原因が提供者か利⽤者のどちらにあるかわかりますか？ ● エラーのメッセージはユーザーのアクションにつながりますか？ ● そのエラーはユーザーアクションに不必要な情報はだしてないですか？

Slide 30

Slide 30 text

No content