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
freee技術の日_freeeのPublic API開発
Search
sereru
April 16, 2023
Programming
0
32k
freee技術の日_freeeのPublic API開発
2023年4月16日に行われたfreee技術の日の発表スライド
freeeのPublic API開発
sereru
April 16, 2023
Tweet
Share
Other Decks in Programming
See All in Programming
Azure AI Foundryではじめてのマルチエージェントワークフロー
seosoft
0
170
『自分のデータだけ見せたい!』を叶える──Laravel × Casbin で複雑権限をスッキリ解きほぐす 25 分
akitotsukahara
2
640
「テストは愚直&&網羅的に書くほどよい」という誤解 / Test Smarter, Not Harder
munetoshi
0
170
AI駆動のマルチエージェントによる業務フロー自動化の設計と実践
h_okkah
0
150
初学者でも今すぐできる、Claude Codeの生産性を10倍上げるTips
s4yuba
16
11k
Code as Context 〜 1にコードで 2にリンタ 34がなくて 5にルール? 〜
yodakeisuke
0
130
PicoRuby on Rails
makicamel
2
130
たった 1 枚の PHP ファイルで実装する MCP サーバ / MCP Server with Vanilla PHP
okashoi
1
250
Discover Metal 4
rei315
2
130
Railsアプリケーションと パフォーマンスチューニング ー 秒間5万リクエストの モバイルオーダーシステムを支える事例 ー Rubyセミナー 大阪
falcon8823
5
1.1k
ruby.wasmで多人数リアルタイム通信ゲームを作ろう
lnit
3
470
今ならAmazon ECSのサービス間通信をどう選ぶか / Selection of ECS Interservice Communication 2025
tkikuc
21
4k
Featured
See All Featured
Agile that works and the tools we love
rasmusluckow
329
21k
Embracing the Ebb and Flow
colly
86
4.7k
Into the Great Unknown - MozCon
thekraken
40
1.9k
Templates, Plugins, & Blocks: Oh My! Creating the theme that thinks of everything
marktimemedia
31
2.4k
Speed Design
sergeychernyshev
32
1k
Sharpening the Axe: The Primacy of Toolmaking
bcantrill
44
2.4k
Optimising Largest Contentful Paint
csswizardry
37
3.3k
Code Review Best Practice
trishagee
69
18k
Docker and Python
trallard
44
3.5k
Let's Do A Bunch of Simple Stuff to Make Websites Faster
chriscoyier
507
140k
VelocityConf: Rendering Performance Case Studies
addyosmani
332
24k
KATA
mclloyd
30
14k
Transcript
freeeのPublic API開発 takayan 2023年4⽉16⽇
ここに円に切り抜いた画像を入れてくだ さい takayan 21年に新卒⼊社 Public API専任チームのAPI基盤ヨットに配属 外部連携開発船API基盤ヨット エンジニア
Public API • Public APIは外部に仕様を公開しているAPI https://developer.freee.co.jp/reference/accounting/reference
freeeはなぜPublic APIを提供しているのか • オープンプラットフォーム構想を志向している ◦ freeeはあらゆる領域のAPIを公開。さまざまなシステムが繋がるエコ システムを構築 • あらゆるシステムが⾃動で繋がるプラットフォームを⽬指している
• ビジョン ◦ だれもが⾃由に経営できる統合型経営プラットフォーム
新規プロダクトでもPublic APIをリリース • freee請求書という新規プロダクトでもPublic APIをリリース
業務アプリのAPIの利⽤者 • freeeは業務アプリとして提供しているので、エンジニアではない、業 務担当者で例えば経理や労務の⽅にも利⽤されています。 ◦ チュートリアルや設計ガイドラインでそういったAPIになれていない ⽅にもご利⽤していただけるようにしています。
freeeのPublic API開発 • freeeではPublic APIを開発する専⾨のチームがある ◦ やってること ◦ freee
public apiの開発 ◦ 他チームが開発する際の public apiの開発⽅針の整備 ◦ webhookの開発 ◦ freee app storeの開発 ◦ freee public apiの共通基盤(new)
Public APIの専任チームをもつことについて • 良い点 ◦ プロダクトを跨いだPublic APIの統⼀的なAPIを実現 ◦ Public
APIの品質をプロダクトを跨いで横断的に管理することができ る ◦ 破壊的変更への注意や影響範囲の感覚が必要なのでそれを⾝につけら れる
Public APIの専任チームをもつことについて • 課題 ◦ プロダクトチームとは別なので予期せぬ破壊的変更を与えることがあ る ◦ プロダクトチームとのやりとりが発⽣してPublic
APIもプロダクト チームでやるよりは決定に時間がかかる ◦ プロダクトが多い場合はコンテキストスイッチが多かったり扱うドメ インが多くなる
freeeのPublic APIの専任チームの今後 • プロダクトやPublic APIの規模が⼩さいときは良い点の利益の⽅が⼤き かったが、だんだん課題が浮き彫りになってきた • 専任チームによりPublic APIの知⾒や運⽤の経験が溜まってきたので、
Public API基盤(Public APIの共通設定など)に従事していくことでAPI の統⼀性は担保しながら、開発⾃体はプロダクトチームが⾏うことで価 値を素早く届けたい 今後
スキーマ駆動開発 • OpenAPI3を⽤いたスキーマを中⼼とした開発を⾏っている ◦ スキーマと呼ばれるものに書かれている定義に基づいて開発する https://github.com/freee/freee-api-schema/blob/master/iv/open-api-3/api-schema.yml ⼀覧取得のAPIの定義のスキーマで、nameがパ ラメータ名で、schema以下でそのパラメータ がどういったものかを定義する
スキーマ駆動開発 • Public API開発に採⽤する利点 ◦ スキーマに基づいた開発をすることで、コードを書く前に利⽤者にど ういったAPIを提供するのがいいのかを考え定義することができる ◦ OpenAPI3でスキーマを定義すればそれが仕様書であり、Public
API のリファレンスにすることができる
スキーマ駆動開発をやっていく上で出た課題 • freee会計のようなプロダクトの規模が⼤きくエンドポイントも多いも ので1つのスキーマファイルで管理すると同時に触ることでコンフリク トが起きやすくなり開発が⾟くなる。 30000⾏を超えるスキーマファイル で全てのエンドポイントを管理する のは⼤変...
スキーマファイルを分割する • これを解決するためにcomponentやpathごとにファイルを分割するこ とでコンフリクトを起こりづらくする。
/components • リクエストボディやレスポンスボディなどのまとまった単位のものをコ ンポーネント化したものの定義
/path • APIを叩く時に使うpathの定義
スキーマ(リファレンス)作成時に重要なこと • 提供しているPublic API全体での統⼀性を意識 ◦ 同⼀の意味で異なるパラメータ名をつけると、利⽤者は本当に同⼀の パラメータなのかを疑わないといけなくなってしまう。 ◦ 新規プロダクトや新規APIでもkey名や構成などの統⼀感を持たせる
ことで他のfreeeのAPIを利⽤したことがあれば利⽤をしやすい状態に する。
スキーマ(リファレンス)作成時に重要なこと • クエリパラメータだとauthorで著者名を指定する。 • レスポンスパラメータはauthor_nameで著者名が返却される。 リクエスト レスポンス
Public APIを運⽤していく上で注意すること 破壊的変更!!
破壊的変更とは • 後⽅互換が保たれておらず、以前と異なる結果を引き起こす変更 API対応図書館を増やした
破壊的変更とは • 図書館のパラメータのリクエストを必須とした結果、今までと同じAPI リクエストがエラーになる curl 'https://api.freee.co.jp/library/books?member_id=1' API対応図書館を増やした
図書館のパラメータ追加で破壊的変更を起こさないには • 図書館のパラメータは必須ではなく任意で追加して、指定されない時は 全ての図書館の蔵書を返却する。 ◦ そのときは、本がどの図書館に含まれてるかもレスポンスしてあげる と良い。 • もしくは、図書館のパラメータは必須ではなく任意で追加して、デフォ
ルトでは挙動が変わらないように最初に対応していた図書館の蔵書のみ を返却する。
レスポンスが異なる破壊的変更 • 著者に他の情報も付け加えよう • authorでまとめてレスポンスしよう ◦ authorの値が異なるものになるので破壊的変更になる 出⽣年の追加
レスポンスが異なる破壊的変更 • 原作者と出版した本を書いた⼈が異なる場合がある • 今返却してるauthorは原作者なのでoriginal_authorに置き換えよう ◦ authorをoriginal_authorとしたので破壊的変更にになる authorを original_authorに置
換
破壊的変更の難しさ • もしバグを含んでリリースしてしまってもそれを前提にAPIを利⽤して いる利⽤者がいる場合は破壊的変更になりバグを気軽に直せない ◦ APIの利⽤者が詳細にどう使っているか把握できないのが難しさに拍 ⾞をかけている • 例えば、プラン制御や権限制御の誤りなどは修正しないといけないが、
厳しくする⽅向に突然修正すると提供しているPublic APIを利⽤してる システムが使えなくなる可能性がある。
freeeでは破壊的変更をする際どうしてるか • 変更の⼤きさや影響を⾒て1ヶ⽉から半年ほど前に告知を出してから変 更する
freeeでは破壊的変更をする際どうしてるか • ⼤規模な仕様変更など積み重なってきた負債を⼀気に解消したい時は、 headerにversionを指定してもらい並⾏期間を設けるようにする https://developers.freee.co.jp/entry/public_api_versioning
None