Upgrade to Pro
— share decks privately, control downloads, hide ads and more …
Speaker Deck
Features
Speaker Deck
PRO
Sign in
Sign up for free
Search
Search
PublicAPIのエラーハンドリング / PublicAPI error handling
Search
freee
June 05, 2024
2
8.5k
PublicAPIのエラーハンドリング / PublicAPI error handling
freee
June 05, 2024
Tweet
Share
More Decks by freee
See All by freee
支出管理船団 エンジニア向け会社説明用資料/Company_Presentation_Materials_for_Fleet_Engineers_in_Expenditure_Management.pdf
freee
0
39
[2025/09/12更新] freeeのAIに関する取り組み
freee
1
360
開発組織発 AI駆動経営
freee
0
170
「SaaS × AI Agentの未来」freee が AWS で築く AI Agent 基盤
freee
0
130
freee が目指す生成 AI 時代に向けた次世代データ プラットフォームとガバナンスとは / freee's Next-Generation Data Platform and Governance for the Coming Age of Generative AI
freee
1
440
freee請求書のSLO違反改善活動について / SLO violation remediation activities for freee invoices
freee
1
480
freee + Product Design FY25Q4
freee
4
17k
10分でわかるfreeeのQA
freee
1
15k
freee Movement Deck
freee
2
360k
Featured
See All Featured
What’s in a name? Adding method to the madness
productmarketing
PRO
24
3.7k
Fight the Zombie Pattern Library - RWD Summit 2016
marcelosomers
234
17k
ReactJS: Keep Simple. Everything can be a component!
pedronauck
667
120k
Principles of Awesome APIs and How to Build Them.
keavy
127
17k
Designing for Performance
lara
610
69k
Templates, Plugins, & Blocks: Oh My! Creating the theme that thinks of everything
marktimemedia
31
2.5k
How to Ace a Technical Interview
jacobian
280
24k
10 Git Anti Patterns You Should be Aware of
lemiorhan
PRO
657
61k
GraphQLとの向き合い方2022年版
quramy
49
14k
A Tale of Four Properties
chriscoyier
161
23k
GraphQLの誤解/rethinking-graphql
sonatard
73
11k
The Language of Interfaces
destraynor
162
25k
Transcript
PublicAPIのエラーハンドリング hyudai 2024年5⽉31⽇
2 hyudai 2022年9月〜API基盤チーム 2023年7月〜外部連携サービス部 クレジットカードとの連携や同期体 験改善に従事 外部連携サービス部エンジニア
コスパよくPublicAPIを運⽤したい
PublicAPIの定義 運⽤負荷の低いPublicAPIを提供する エラーにおけるセキュリティ ⽬次
(この登壇における)PublicAPIの定義 会社外に向けて発信するAPI全般 PublicAPIに該当するもの
(この登壇における)PublicAPIの定義 会社外に向けて発信するAPI全般 PublicAPIに該当するもの • freee会計などの不特定多数に向けて提供されるAPI freee Developers Community https://developer.freee.co.jp/
(この登壇における)PublicAPIの定義 会社外に向けて発信するAPI全般 PublicAPIに該当するもの • freee会計などの不特定多数に向けて提供されるAPI • ⼀般公開していないが、外部の企業との通信に使⽤するAPI
(この登壇における)PublicAPIの定義 PublicAPIに該当しないもの
(この登壇における)PublicAPIの定義 PublicAPIに該当しないもの • ⾃社内での利⽤のみを想定した通信 ◦ private API ◦ マイクロサービス間の通信
• プログラム間の通信以外の⽬的で作られたもの ◦ UIを提供するHTML
PublicAPIに該当するもの • freee会計などの不特定多数に向けて提供されるAPI • ⼀般公開していないが、外部の企業との通信に使⽤するAPI PublicAPIに該当しないもの • ⾃社内での利⽤のみを想定した通信 ◦
private API ◦ マイクロサービス間の通信 • プログラム間の通信以外の⽬的で作られたもの ◦ UIを提供するHTML
⼀般公開されていないAPIをPublicAPIに含める理由 コミュニケーションコストが無視できない
⼀般公開されていないAPIをPublicAPIに含める理由 コミュニケーションコストが無視できない 社内の場合 • 問題が発⽣した時にslackなどのツールですぐに連絡を取れる • 内部だからこそ機密情報を使ったやりとりができる ◦ このAPIは
N + 1が潜んでいるのであんまり叩かないで欲しいなど
⼀般公開されていないAPIをPublicAPIに含める理由 コミュニケーションコストが無視できない 社外の場合 • mailでのやり取りになる ◦ ビジネス⽂書に慣れていない場合は内部レビューが⼊ることも • 機密情報を伝えることは難しいので情報伝達の粒度が荒くなる
◦ 粒度が荒くなるのに正確性を要求される • 連絡を送ったとしても返信がいつになるのかわからない ◦ 返信が1,2週間遅れることも...
⼀般公開されていないAPIをPublicAPIに含める理由 コミュニケーションコストが無視できない 問い合わせ時の対応について API利⽤者側 ◦ 社内である程度調べ上げて確からしいという仮説が⽴った状態 ◦ 調べ上げた結果何にもわからなかった時... API提供者側
◦ 精度の⾼い状態で返信を送らなければならない ◦ アクセスログとかまで⾒に⾏く必要があるかもしれない
⼀般公開されていないAPIをPublicAPIに含める理由 この問題は⼀般公開されているAPIであっても同じですよね?
運⽤負荷の低いPublicAPIを提供する ユーザーに⾃⼰解決をしてもらうことが重要 • エラーを充実させる • チュートリアルを含めたドキュメントの整備 ◦ 最初にAPIを叩くまでの時間が⼀番挫折しやすい(IMO) •
SDKやライブラリを提供する
運⽤負荷の低いPublicAPIを提供する ユーザーに⾃⼰解決をしてもらうことが重要 • エラーを充実させる • チュートリアルを含めたドキュメントの整備 ◦ 最初にAPIを叩くまでの時間が⼀番挫折しやすい(IMO) •
SDKやライブラリを提供する
運⽤負荷の低いPublicAPIを提供する エラーを充実させる 問題の特定 • ステータスを充実させることで提供者と利⽤者のどちらに問題があるの かを明確にする • 状況に合わせた対応策を提⽰ •
ステータスコード200,400,500をちゃんと使い分けることが⼤事
運⽤負荷の低いPublicAPIを提供する エラーを充実させる 問題の特定 • ステータスを充実させることで提供者と利⽤者のどちらに問題があるの かを明確にする • 状況に合わせた対応策を提⽰ •
ステータスコード200,400,500をちゃんと使い分けることが⼤事 問題が発⽣した際のユーザーのアクションを案内 • ⼊⼒データ形式をXYZに修正してください • rate limitです
もしエラーが整備されていないAPIだと? APIの仕様 常に200okでレスポンスされるAPI 成功しても失敗しても200、⼆つの違いはresponseのみ シナリオ 会計ソフトに登録している固定資産の数を調べたくてindexのAPIを叩いた ら200okで返ってきた!ただしbodyは空っぽ この時のデータは次のうちどちらの解釈をすればいい? •
本当に固定資産が何もない時 • ⼊⼒値が間違えてエラーになった時
もしエラーが整備されていないAPIだと? APIの仕様 成功すると200, 失敗すると500が返ってくる。 エラーメッセージは常に「エラーが発⽣しました」 シナリオ すでに運⽤に乗っているサービスで、とある会社との通信に使⽤している APIが急に500エラーを返してきた。
もしエラーが整備されていないAPIだと? シナリオ すでに運⽤に乗っているサービスで、とある会社との通信に使⽤している APIが急に500エラーを返してきた。 まずどっちの問題...? • 先⽅のサーバーが落ちた? • リクエストの形式が不正...?でも今まで動いてたし...
もしエラーが整備されていないAPIだと? シナリオ すでに運⽤に乗っているサービスで、とある会社との通信に使⽤している APIが急に500エラーを返してきた。 調査に難航したため問い合わせをしたところ • 「実装時からリクエストの形式が不正だったが、内部でvalidationする ようにした」 ◦
利⽤者側: 先⽅の都合はわからない ◦ 提供者側: バグを修正したら問い合わせが増えた... どちらも幸せにならない結末になるかもしれません
もしエラーが整備されていないAPIだと? 先ほど例に出したAPIはフィクションです。 ただ、エラーメッセージがないと⾏える調査にも限界があります。2つ⽬に紹介 したものはどちらかというとAPI利⽤者側の実装ミス起因ですが、それすらも⾃ ⼰解決することは難しいです。 不適切なエラーを提供しているAPIは結果として⾃らの保守運⽤コストが犠牲に なります。
エラーにおけるセキュリティ エラーを整備する壁は⼤きく分けて2つ • 内部のエラーとは異なる • セキュリティ
エラーにおけるセキュリティ PublicAPIのみを提供しているサービスは少ない ⼤体は⼤元のサービスから切り出して、PublicAPI「でも」使えるように している 内部のエラーを流⽤している結果、ユーザーフレンドリーじゃないものが 出来上がる可能性も • PublicAPIを使うのは職業エンジニアだけではない •
そもそも内部のエラーは⾒られていい状態になってますか?
エラーにおけるセキュリティ エラーを詳細に書きすぎるリスク • 内部情報の漏洩 ◦ 現在のCPU使⽤率が80% overなので使⽤をやめてください • セキュリティレベルが極めて⾼い情報を出してしまった
では何を返せばいいの?
エラーにおけるセキュリティ ユーザーに何をして欲しいのかを明確にすることが大事 freee会計のAPIでcompany_idを不正なパラメータの時の例 { "message": "この事業所にアクセスする権限がありません", "code":
"invalid_authorization_company_id" } 何を確認すればいいのかはわかりますよね? ただし情報漏洩には気をつけてください
終わりに コスパ良いPublicAPIの提供を⾏うために気を付けること • エラーの原因が提供者か利⽤者のどちらにあるかわかりますか? • エラーのメッセージはユーザーのアクションにつながりますか? • そのエラーはユーザーアクションに不必要な情報はだしてないですか?
None