Upgrade to Pro — share decks privately, control downloads, hide ads and more …

freee技術の日_freeeのPublic API開発

sereru
April 16, 2023

freee技術の日_freeeのPublic API開発

2023年4月16日に行われたfreee技術の日の発表スライド
freeeのPublic API開発

sereru

April 16, 2023
Tweet

Other Decks in Programming

Transcript

  1. freeeのPublic API開発
    takayan
    2023年4⽉16⽇

    View full-size slide

  2. ここに円に切り抜いた画像を入れてくだ
    さい
    takayan
    21年に新卒⼊社
    Public API専任チームのAPI基盤ヨットに配属
    外部連携開発船API基盤ヨット エンジニア

    View full-size slide

  3.  
    Public API
    ● Public APIは外部に仕様を公開しているAPI
    https://developer.freee.co.jp/reference/accounting/reference

    View full-size slide

  4.  
    freeeはなぜPublic APIを提供しているのか
    ● オープンプラットフォーム構想を志向している
    ○ freeeはあらゆる領域のAPIを公開。さまざまなシステムが繋がるエコ
    システムを構築
    ● あらゆるシステムが⾃動で繋がるプラットフォームを⽬指している
    ● ビジョン
    ○ だれもが⾃由に経営できる統合型経営プラットフォーム

    View full-size slide

  5.  
    新規プロダクトでもPublic APIをリリース
    ● freee請求書という新規プロダクトでもPublic APIをリリース

    View full-size slide

  6.  
    業務アプリのAPIの利⽤者
    ● freeeは業務アプリとして提供しているので、エンジニアではない、業
    務担当者で例えば経理や労務の⽅にも利⽤されています。
    ○ チュートリアルや設計ガイドラインでそういったAPIになれていない
    ⽅にもご利⽤していただけるようにしています。

    View full-size slide

  7.  
    freeeのPublic API開発
    ● freeeではPublic APIを開発する専⾨のチームがある
    ○ やってること
    ○ freee public apiの開発
    ○ 他チームが開発する際の public apiの開発⽅針の整備
    ○ webhookの開発
    ○ freee app storeの開発
    ○ freee public apiの共通基盤(new)

    View full-size slide

  8.  
    Public APIの専任チームをもつことについて
    ● 良い点
    ○ プロダクトを跨いだPublic APIの統⼀的なAPIを実現
    ○ Public APIの品質をプロダクトを跨いで横断的に管理することができ

    ○ 破壊的変更への注意や影響範囲の感覚が必要なのでそれを⾝につけら
    れる

    View full-size slide

  9.  
    Public APIの専任チームをもつことについて
    ● 課題
    ○ プロダクトチームとは別なので予期せぬ破壊的変更を与えることがあ

    ○ プロダクトチームとのやりとりが発⽣してPublic APIもプロダクト
    チームでやるよりは決定に時間がかかる
    ○ プロダクトが多い場合はコンテキストスイッチが多かったり扱うドメ
    インが多くなる

    View full-size slide

  10.  
    freeeのPublic APIの専任チームの今後
    ● プロダクトやPublic APIの規模が⼩さいときは良い点の利益の⽅が⼤き
    かったが、だんだん課題が浮き彫りになってきた
    ● 専任チームによりPublic APIの知⾒や運⽤の経験が溜まってきたので、
    Public API基盤(Public APIの共通設定など)に従事していくことでAPI
    の統⼀性は担保しながら、開発⾃体はプロダクトチームが⾏うことで価
    値を素早く届けたい
    今後

    View full-size slide

  11.  
    スキーマ駆動開発
    ● OpenAPI3を⽤いたスキーマを中⼼とした開発を⾏っている
    ○ スキーマと呼ばれるものに書かれている定義に基づいて開発する
    https://github.com/freee/freee-api-schema/blob/master/iv/open-api-3/api-schema.yml
    ⼀覧取得のAPIの定義のスキーマで、nameがパ
    ラメータ名で、schema以下でそのパラメータ
    がどういったものかを定義する

    View full-size slide

  12.  
    スキーマ駆動開発
    ● Public API開発に採⽤する利点
    ○ スキーマに基づいた開発をすることで、コードを書く前に利⽤者にど
    ういったAPIを提供するのがいいのかを考え定義することができる
    ○ OpenAPI3でスキーマを定義すればそれが仕様書であり、Public API
    のリファレンスにすることができる

    View full-size slide

  13.  
    スキーマ駆動開発をやっていく上で出た課題
    ● freee会計のようなプロダクトの規模が⼤きくエンドポイントも多いも
    ので1つのスキーマファイルで管理すると同時に触ることでコンフリク
    トが起きやすくなり開発が⾟くなる。
    30000⾏を超えるスキーマファイル
    で全てのエンドポイントを管理する
    のは⼤変...

    View full-size slide

  14.  
    スキーマファイルを分割する
    ● これを解決するためにcomponentやpathごとにファイルを分割するこ
    とでコンフリクトを起こりづらくする。

    View full-size slide

  15.  
    /components
    ● リクエストボディやレスポンスボディなどのまとまった単位のものをコ
    ンポーネント化したものの定義

    View full-size slide

  16.  
    /path
    ● APIを叩く時に使うpathの定義

    View full-size slide

  17.  
    スキーマ(リファレンス)作成時に重要なこと
    ● 提供しているPublic API全体での統⼀性を意識
    ○ 同⼀の意味で異なるパラメータ名をつけると、利⽤者は本当に同⼀の
    パラメータなのかを疑わないといけなくなってしまう。
    ○ 新規プロダクトや新規APIでもkey名や構成などの統⼀感を持たせる
    ことで他のfreeeのAPIを利⽤したことがあれば利⽤をしやすい状態に
    する。

    View full-size slide

  18.  
    スキーマ(リファレンス)作成時に重要なこと
    ● クエリパラメータだとauthorで著者名を指定する。
    ● レスポンスパラメータはauthor_nameで著者名が返却される。
    リクエスト レスポンス

    View full-size slide

  19.  
    Public APIを運⽤していく上で注意すること
    破壊的変更!!

    View full-size slide

  20.  
    破壊的変更とは
    ● 後⽅互換が保たれておらず、以前と異なる結果を引き起こす変更
    API対応図書館を増やした

    View full-size slide

  21.  
    破壊的変更とは
    ● 図書館のパラメータのリクエストを必須とした結果、今までと同じAPI
    リクエストがエラーになる
    curl 'https://api.freee.co.jp/library/books?member_id=1'
    API対応図書館を増やした

    View full-size slide

  22.  
    図書館のパラメータ追加で破壊的変更を起こさないには
    ● 図書館のパラメータは必須ではなく任意で追加して、指定されない時は
    全ての図書館の蔵書を返却する。
    ○ そのときは、本がどの図書館に含まれてるかもレスポンスしてあげる
    と良い。
    ● もしくは、図書館のパラメータは必須ではなく任意で追加して、デフォ
    ルトでは挙動が変わらないように最初に対応していた図書館の蔵書のみ
    を返却する。

    View full-size slide

  23.  
    レスポンスが異なる破壊的変更
    ● 著者に他の情報も付け加えよう
    ● authorでまとめてレスポンスしよう
    ○ authorの値が異なるものになるので破壊的変更になる
    出⽣年の追加

    View full-size slide

  24.  
    レスポンスが異なる破壊的変更
    ● 原作者と出版した本を書いた⼈が異なる場合がある
    ● 今返却してるauthorは原作者なのでoriginal_authorに置き換えよう
    ○ authorをoriginal_authorとしたので破壊的変更にになる
    authorを
    original_authorに置

    View full-size slide

  25.  
    破壊的変更の難しさ
    ● もしバグを含んでリリースしてしまってもそれを前提にAPIを利⽤して
    いる利⽤者がいる場合は破壊的変更になりバグを気軽に直せない
    ○ APIの利⽤者が詳細にどう使っているか把握できないのが難しさに拍
    ⾞をかけている
    ● 例えば、プラン制御や権限制御の誤りなどは修正しないといけないが、
    厳しくする⽅向に突然修正すると提供しているPublic APIを利⽤してる
    システムが使えなくなる可能性がある。

    View full-size slide

  26.  
    freeeでは破壊的変更をする際どうしてるか
    ● 変更の⼤きさや影響を⾒て1ヶ⽉から半年ほど前に告知を出してから変
    更する

    View full-size slide

  27.  
    freeeでは破壊的変更をする際どうしてるか
    ● ⼤規模な仕様変更など積み重なってきた負債を⼀気に解消したい時は、
    headerにversionを指定してもらい並⾏期間を設けるようにする
    https://developers.freee.co.jp/entry/public_api_versioning

    View full-size slide