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
3.5k
PublicAPIのエラーハンドリング / PublicAPI error handling
freee
June 05, 2024
Tweet
Share
More Decks by freee
See All by freee
freee + Product Design FY24 Q2
freee
4
9.4k
freeeのモバイルエンジニアについて
freee
1
200
10分でわかるfreeeのQA
freee
1
4.2k
10分でわかるfreee エンジニア向け会社説明資料
freee
18
530k
freeeの福利厚生と働き方
freee
1
66k
品質の高速フィードバックへの取り組み / Commitment to Fast Quality Feedback
freee
4
1.1k
組織作りに「プロダクト開発のエッセンス」 を取り入れ、不確実性に向き合い続ける / Incorporating the “essence of product development” into organizational development and continuing to face uncertainty
freee
0
2.7k
LGBTQ__support_WOMEN_女性として働くということ_DEI
freee
2
510
QAエンジニア_Summer Internship説明会(26卒)
freee
0
270
Featured
See All Featured
Six Lessons from altMBA
skipperchong
27
3.5k
10 Git Anti Patterns You Should be Aware of
lemiorhan
PRO
656
59k
I Don’t Have Time: Getting Over the Fear to Launch Your Podcast
jcasabona
29
2k
Build your cross-platform service in a week with App Engine
jlugia
229
18k
Learning to Love Humans: Emotional Interface Design
aarron
273
40k
The Psychology of Web Performance [Beyond Tellerrand 2023]
tammyeverts
45
2.2k
Imperfection Machines: The Place of Print at Facebook
scottboms
266
13k
ピンチをチャンスに:未来をつくるプロダクトロードマップ #pmconf2020
aki_iinuma
111
49k
Done Done
chrislema
181
16k
The Illustrated Children's Guide to Kubernetes
chrisshort
48
48k
The Invisible Side of Design
smashingmag
298
50k
[RailsConf 2023] Rails as a piece of cake
palkan
53
5k
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