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
2.3k
PublicAPIのエラーハンドリング / PublicAPI error handling
freee
June 05, 2024
Tweet
Share
More Decks by freee
See All by freee
品質の高速フィードバックへの取り組み / Commitment to Fast Quality Feedback
freee
3
790
組織作りに「プロダクト開発のエッセンス」 を取り入れ、不確実性に向き合い続ける / Incorporating the “essence of product development” into organizational development and continuing to face uncertainty
freee
0
1.2k
LGBTQ__support_WOMEN_女性として働くということ_DEI
freee
2
420
QAエンジニア_Summer Internship説明会(26卒)
freee
0
220
権限管理基盤の開発とQAの今 / Authority Management Infrastructure Development and QA Now
freee
1
2.3k
国籍と専門性を超えてのコラボレーション / Collaboration across nationalities and specialties
freee
1
2.2k
デザインリサーチの広げ方 〜XDの姿勢・態度・思考〜 / How to Expand Design Research 〜˜XD's Attitude, Attitude, and Thinking
freee
1
2.2k
グローバルなQAエンジニア・・・ってナニ!? / Global_QA_Engineer..._What_s_that.pdf
freee
1
2.2k
ぶきっちょPMによるfreeeのカルチャーとプロダクトのつながりについて / The Connection Between Freee's Culture and Product by a Clumsy PM
freee
1
2.2k
Featured
See All Featured
Rebuilding a faster, lazier Slack
samanthasiow
79
8.6k
The Myth of the Modular Monolith - Day 2 Keynote - Rails World 2024
eileencodes
6
260
Bootstrapping a Software Product
garrettdimon
PRO
304
110k
Product Roadmaps are Hard
iamctodd
PRO
48
10k
WebSockets: Embracing the real-time Web
robhawkes
59
7.3k
Refactoring Trust on Your Teams (GOTO; Chicago 2020)
rmw
30
2.6k
Design by the Numbers
sachag
278
19k
Building an army of robots
kneath
302
42k
ピンチをチャンスに:未来をつくるプロダクトロードマップ #pmconf2020
aki_iinuma
105
48k
Making the Leap to Tech Lead
cromwellryan
130
8.8k
Building Your Own Lightsaber
phodgson
102
6k
The Invisible Customer
myddelton
119
13k
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