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
スタートアップの急成長を支えるプラットフォームエンジニアリングと組織戦略
sutochin26
1
5.8k
PHPで始める振る舞い駆動開発(Behaviour-Driven Development)
ohmori_yusuke
2
390
明示と暗黙 ー PHPとGoの インターフェイスの違いを知る
shimabox
2
510
Azure AI Foundryではじめてのマルチエージェントワークフロー
seosoft
0
170
地方に住むエンジニアの残酷な現実とキャリア論
ichimichi
5
1.5k
Deep Dive into ~/.claude/projects
hiragram
14
2.6k
新メンバーも今日から大活躍!SREが支えるスケールし続ける組織のオンボーディング
honmarkhunt
5
7.4k
AIともっと楽するE2Eテスト
myohei
6
2.6k
Google Agent Development Kit でLINE Botを作ってみた
ymd65536
2
250
設計やレビューに悩んでいるPHPerに贈る、クリーンなオブジェクト設計の指針たち
panda_program
6
2.1k
今ならAmazon ECSのサービス間通信をどう選ぶか / Selection of ECS Interservice Communication 2025
tkikuc
21
4k
0626 Findy Product Manager LT Night_高田スライド_speaker deck用
mana_takada
0
170
Featured
See All Featured
No one is an island. Learnings from fostering a developers community.
thoeni
21
3.4k
The World Runs on Bad Software
bkeepers
PRO
69
11k
Raft: Consensus for Rubyists
vanstee
140
7k
Building Better People: How to give real-time feedback that sticks.
wjessup
367
19k
Designing for humans not robots
tammielis
253
25k
Sharpening the Axe: The Primacy of Toolmaking
bcantrill
44
2.4k
VelocityConf: Rendering Performance Case Studies
addyosmani
332
24k
Learning to Love Humans: Emotional Interface Design
aarron
273
40k
Practical Tips for Bootstrapping Information Extraction Pipelines
honnibal
PRO
20
1.3k
Java REST API Framework Comparison - PWX 2021
mraible
31
8.7k
Embracing the Ebb and Flow
colly
86
4.7k
Building Flexible Design Systems
yeseniaperezcruz
328
39k
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