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
26k
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
DevFest Android in Korea 2024 - 안드로이드의 문단속 : 앱을 지키는 암호화 이야기
mdb1217
1
160
Повторное использование кода в ML: почему ML-пайплайны могут помочь?
lamodatech
0
150
メルカリ ハロ アプリの技術スタック
atsumo
2
790
(Deep|Web) Link support with expo-router
mrtry
0
170
"Swarming" をコンセプトに掲げるアジャイルチームのベストプラクティス
boykush
2
250
"noncopyable types" の使いどころについて考えてみた
andpad
0
150
Iteratorでページネーションを実現する
sonatard
3
710
Introduce dRuby
ledsun
0
110
モジュラモノリス、その前に / Modular monolith, before that
euglena1215
6
690
Beyond Laravel Octane - Hyperf for Laravel Artisans
albertcht
1
130
フロントエンドの現在地とこれから
koba04
10
4.5k
利用者視点で考える、イテレータとの上手な付き合い方
syumai
4
230
Featured
See All Featured
Into the Great Unknown - MozCon
thekraken
31
1.4k
Code Review Best Practice
trishagee
62
16k
10 Git Anti Patterns You Should be Aware of
lemiorhan
653
59k
"I'm Feeling Lucky" - Building Great Search Experiences for Today's Users (#IAC19)
danielanewman
225
22k
The Psychology of Web Performance [Beyond Tellerrand 2023]
tammyeverts
39
2.1k
How to Ace a Technical Interview
jacobian
275
23k
In The Pink: A Labor of Love
frogandcode
139
22k
The Brand Is Dead. Long Live the Brand.
mthomps
53
38k
[RailsConf 2023] Rails as a piece of cake
palkan
49
4.7k
Save Time (by Creating Custom Rails Generators)
garrettdimon
PRO
25
660
Product Roadmaps are Hard
iamctodd
PRO
48
10k
A Tale of Four Properties
chriscoyier
156
22k
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