Slide 1
Slide 1 text
freeeのPublic API開発
takayan
2023年4⽉16⽇
Slide 2
Slide 2 text
ここに円に切り抜いた画像を入れてくだ
さい
takayan
21年に新卒⼊社
Public API専任チームのAPI基盤ヨットに配属
外部連携開発船API基盤ヨット エンジニア
Slide 3
Slide 3 text
Public API
● Public APIは外部に仕様を公開しているAPI
https://developer.freee.co.jp/reference/accounting/reference
Slide 4
Slide 4 text
freeeはなぜPublic APIを提供しているのか
● オープンプラットフォーム構想を志向している
○ freeeはあらゆる領域のAPIを公開。さまざまなシステムが繋がるエコ
システムを構築
● あらゆるシステムが⾃動で繋がるプラットフォームを⽬指している
● ビジョン
○ だれもが⾃由に経営できる統合型経営プラットフォーム
Slide 5
Slide 5 text
新規プロダクトでもPublic APIをリリース
● freee請求書という新規プロダクトでもPublic APIをリリース
Slide 6
Slide 6 text
業務アプリのAPIの利⽤者
● freeeは業務アプリとして提供しているので、エンジニアではない、業
務担当者で例えば経理や労務の⽅にも利⽤されています。
○ チュートリアルや設計ガイドラインでそういったAPIになれていない
⽅にもご利⽤していただけるようにしています。
Slide 7
Slide 7 text
freeeのPublic API開発
● freeeではPublic APIを開発する専⾨のチームがある
○ やってること
○ freee public apiの開発
○ 他チームが開発する際の public apiの開発⽅針の整備
○ webhookの開発
○ freee app storeの開発
○ freee public apiの共通基盤（new）
Slide 8
Slide 8 text
Public APIの専任チームをもつことについて
● 良い点
○ プロダクトを跨いだPublic APIの統⼀的なAPIを実現
○ Public APIの品質をプロダクトを跨いで横断的に管理することができ
る
○ 破壊的変更への注意や影響範囲の感覚が必要なのでそれを⾝につけら
れる
Slide 9
Slide 9 text
Public APIの専任チームをもつことについて
● 課題
○ プロダクトチームとは別なので予期せぬ破壊的変更を与えることがあ
る
○ プロダクトチームとのやりとりが発⽣してPublic APIもプロダクト
チームでやるよりは決定に時間がかかる
○ プロダクトが多い場合はコンテキストスイッチが多かったり扱うドメ
インが多くなる
Slide 10
Slide 10 text
freeeのPublic APIの専任チームの今後
● プロダクトやPublic APIの規模が⼩さいときは良い点の利益の⽅が⼤き
かったが、だんだん課題が浮き彫りになってきた
● 専任チームによりPublic APIの知⾒や運⽤の経験が溜まってきたので、
Public API基盤（Public APIの共通設定など）に従事していくことでAPI
の統⼀性は担保しながら、開発⾃体はプロダクトチームが⾏うことで価
値を素早く届けたい
今後
Slide 11
Slide 11 text
スキーマ駆動開発
● OpenAPI3を⽤いたスキーマを中⼼とした開発を⾏っている
○ スキーマと呼ばれるものに書かれている定義に基づいて開発する
https://github.com/freee/freee-api-schema/blob/master/iv/open-api-3/api-schema.yml
⼀覧取得のAPIの定義のスキーマで、nameがパ
ラメータ名で、schema以下でそのパラメータ
がどういったものかを定義する
Slide 12
Slide 12 text
スキーマ駆動開発
● Public API開発に採⽤する利点
○ スキーマに基づいた開発をすることで、コードを書く前に利⽤者にど
ういったAPIを提供するのがいいのかを考え定義することができる
○ OpenAPI3でスキーマを定義すればそれが仕様書であり、Public API
のリファレンスにすることができる
Slide 13
Slide 13 text
スキーマ駆動開発をやっていく上で出た課題
● freee会計のようなプロダクトの規模が⼤きくエンドポイントも多いも
ので1つのスキーマファイルで管理すると同時に触ることでコンフリク
トが起きやすくなり開発が⾟くなる。
30000⾏を超えるスキーマファイル
で全てのエンドポイントを管理する
のは⼤変...
Slide 14
Slide 14 text
スキーマファイルを分割する
● これを解決するためにcomponentやpathごとにファイルを分割するこ
とでコンフリクトを起こりづらくする。
Slide 15
Slide 15 text
/components
● リクエストボディやレスポンスボディなどのまとまった単位のものをコ
ンポーネント化したものの定義
Slide 16
Slide 16 text
/path
● APIを叩く時に使うpathの定義
Slide 17
Slide 17 text
スキーマ（リファレンス）作成時に重要なこと
● 提供しているPublic API全体での統⼀性を意識
○ 同⼀の意味で異なるパラメータ名をつけると、利⽤者は本当に同⼀の
パラメータなのかを疑わないといけなくなってしまう。
○ 新規プロダクトや新規APIでもkey名や構成などの統⼀感を持たせる
ことで他のfreeeのAPIを利⽤したことがあれば利⽤をしやすい状態に
する。
Slide 18
Slide 18 text
スキーマ（リファレンス）作成時に重要なこと
● クエリパラメータだとauthorで著者名を指定する。
● レスポンスパラメータはauthor_nameで著者名が返却される。
リクエスト レスポンス
Slide 19
Slide 19 text
Public APIを運⽤していく上で注意すること
破壊的変更!!
Slide 20
Slide 20 text
破壊的変更とは
● 後⽅互換が保たれておらず、以前と異なる結果を引き起こす変更
API対応図書館を増やした
Slide 21
Slide 21 text
破壊的変更とは
● 図書館のパラメータのリクエストを必須とした結果、今までと同じAPI
リクエストがエラーになる
curl 'https://api.freee.co.jp/library/books?member_id=1'
API対応図書館を増やした
Slide 22
Slide 22 text
図書館のパラメータ追加で破壊的変更を起こさないには
● 図書館のパラメータは必須ではなく任意で追加して、指定されない時は
全ての図書館の蔵書を返却する。
○ そのときは、本がどの図書館に含まれてるかもレスポンスしてあげる
と良い。
● もしくは、図書館のパラメータは必須ではなく任意で追加して、デフォ
ルトでは挙動が変わらないように最初に対応していた図書館の蔵書のみ
を返却する。
Slide 23
Slide 23 text
レスポンスが異なる破壊的変更
● 著者に他の情報も付け加えよう
● authorでまとめてレスポンスしよう
○ authorの値が異なるものになるので破壊的変更になる
出⽣年の追加
Slide 24
Slide 24 text
レスポンスが異なる破壊的変更
● 原作者と出版した本を書いた⼈が異なる場合がある
● 今返却してるauthorは原作者なのでoriginal_authorに置き換えよう
○ authorをoriginal_authorとしたので破壊的変更にになる
authorを
original_authorに置
換
Slide 25
Slide 25 text
破壊的変更の難しさ
● もしバグを含んでリリースしてしまってもそれを前提にAPIを利⽤して
いる利⽤者がいる場合は破壊的変更になりバグを気軽に直せない
○ APIの利⽤者が詳細にどう使っているか把握できないのが難しさに拍
⾞をかけている
● 例えば、プラン制御や権限制御の誤りなどは修正しないといけないが、
厳しくする⽅向に突然修正すると提供しているPublic APIを利⽤してる
システムが使えなくなる可能性がある。
Slide 26
Slide 26 text
freeeでは破壊的変更をする際どうしてるか
● 変更の⼤きさや影響を⾒て1ヶ⽉から半年ほど前に告知を出してから変
更する
Slide 27
Slide 27 text
freeeでは破壊的変更をする際どうしてるか
● ⼤規模な仕様変更など積み重なってきた負債を⼀気に解消したい時は、
headerにversionを指定してもらい並⾏期間を設けるようにする
https://developers.freee.co.jp/entry/public_api_versioning
Slide 28
Slide 28 text
No content