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
21k
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
検証も兼ねて個人開発でHonoとかと向き合った話
hanetsuki
1
1.4k
R言語の環境構築と基礎 Tokyo.R 112
bob3bob3
0
280
Documentation for users with AsciiDoc and Antora
ahus1
0
370
Native Federation: The Future of Micro Frontends in Angular
manfredsteyer
PRO
0
120
Sheets API使ってみた
toshi0383
2
170
Direct Style Effect Systems The Print[A] ExampleA Comprehension Aid
philipschwarz
PRO
0
180
Node.js v22 で変わること
yosuke_furukawa
PRO
12
4k
CREってこういうこと? 体験入社 - 提案資料 - / what-is-cre-trial-employment
shinden
1
560
Azure OpenAI Serviceのプロンプトエンジニアリング入門
tomokusaba
3
910
パフォーマンスを求めてDBに機能を寄せる戦略
aoyagikouhei
0
110
障害対応を起点としたもっといい開発と運用のサイクル作りのためにできること / Hatena Enginner Seminar #29
polamjag
0
410
Fragment Composition of GraphQL
quramy
13
1.5k
Featured
See All Featured
Design and Strategy: How to Deal with People Who Don’t "Get" Design
morganepeng
117
18k
Cheating the UX When There Is Nothing More to Optimize - PixelPioneers
stephaniewalter
275
13k
[Rails World 2023 - Day 1 Closing Keynote] - The Magic of Rails
eileencodes
9
1.3k
Producing Creativity
orderedlist
PRO
338
39k
Intergalactic Javascript Robots from Outer Space
tanoku
266
26k
Build The Right Thing And Hit Your Dates
maggiecrowley
25
2k
Designing for humans not robots
tammielis
247
25k
Why You Should Never Use an ORM
jnunemaker
PRO
51
8.7k
Put a Button on it: Removing Barriers to Going Fast.
kastner
58
3.1k
The Cost Of JavaScript in 2023
addyosmani
21
3.9k
Typedesign – Prime Four
hannesfritz
36
2.1k
Building Effective Engineering Teams - LeadDev
addyosmani
32
1.9k
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