エンジニア未経験のプロダクトマネージャーが、エンジニア留学のために勉強したこと

こんにちは。プロダクトマネージャーのmikiです。今回はじめての投稿ですので、簡単に自己紹介をさせていただきます。

私は4年ほど前にfreeeに入社しました。最初の2年はカスタマーサクセスとして、会計事務所さん・IPOユーザーさん・API連携希望ユーザーさんなどの様々な導入支援を担当し、その後、アライアンス事業部にて、パートナープログラムの策定・パートナー企業内でのカスタマーサクセスチームの立ち上げのご支援をしてきました。そして最近プロダクトマネージャーに異動になり、公式アプリを担当しております。

そして実は、現在はプロダクトマネージャー業務はお休みしていて、エンジニア留学の1期生として1月からAPIチームに参画し、エンジニアとして働いております。

エンジニア留学とは

freee社内の留学制度でエンジニアではない人が、3ヶ月間、エンジニアチームに一時的に参画し、エンジニアとして業務を遂行し、学習を深める制度です。

エンジニア留学へのマネージャーからの期待値(ミッション)

  • プロダクトマネージャーは開発チームと技術的なコミュニケーションができる必要がある。特に公式アプリはデベロッパーと直接の技術コミュニケーションが多いので業務知識に加え、より深い技術理解が必要である。 そのために必要な技術や開発プロセスおよび開発の勘所(仕様を一つ追加することの開発的なリスク、リファクタの必要性、どこまで詳細に仕様つめる必要があるか、開発にかかる工数など)を座学に加え、実務経験を通して学習してくること。

1週間の過ごしかた

マネージャーからの受け取ったミッションを達成するべく、現在の1週間のスケジュールはこんな感じで、なるべく起きている時間のほとんどはプログラミングの勉強に当てるようにしています。

1週間のスケジュール。朝6時から9時までは勉強、土日はほとんど勉強。

社内のイベント登壇用に作成したもので、少し時間のメモリが粗いことは多めにみてやってください。

エンジニア留学に向けた準備

エンジニア留学の1期生として年明けからエンジニアになるよ!とマネージャーから話をもらったのは12月の上旬のことでした。それから留学をするにあたって、少しずつ準備をはじめました。

PCをWindowsからMacに変える

エンジニアのほとんどの人がMacを使っていて、技術の解説はMacであることが多いとのことで、環境は合わせた方がいいと思い、変更しました。

仲間を作る

留学にあたって、基礎力となるプログラミング言語は独学での習得が不可欠でした。私は、なにかを学習するときは決まって、仲間を作るとうまくいくタイプだったので、オンラインのもくもく会に参加したり、もくもく会を開催したり、2月末を目標にHTML/CSS/JavaScript/Reactまで一緒に勉強したい人を募集して学習グループを結成してみたりと、積極的に駆け出しエンジニアの仲間を作る活動を行いました。

自己育成計画書を作成し学習を進める

これは新しい部署に異動するときには必ずやっていることです。自分がなにか新しいことを吸収してる期間は目に見えるアウトプットを出しづらいため、自分は世の中の役に立ってるんだろうかという気持ちが蔓延し、必要以上に自己肯定感が下がりやすい傾向にあると自己理解しています。トップスピードのまま3ヶ月間を駆け抜けられるように、自分がどれくらい昨日より今日、進歩したのかわかるようにスプレッドシートにて計画とその進捗管理を行い、モチベーションが下がらない工夫をしました。

今回は、上記3つの中でも、自己育成計画をピックアップし、 計画を立てる上で、非常に参考になりましたフロントエンドのロードマップ に沿ってどのように学習したかをご紹介させていただきます。

フロントエンドのロードマップ

roadmap.sh

これは@kamranahmedse さんが作成されたフロントエンド開発・運用に必要なスキルや知識・ツールなどをひとまとめにしてくれているロードマップ です。 上記のサイトに定期的にバージョンアップされながら公開されているようです。

ありがたいことに@TetsuKinomuraさんによる日本語版もあるので、こちらも貼っておきます。

さらに、親切なことにYouTuberのトラハックさんがこのロードマップについて解説もしてくれていました。これにより何を勉強しなければならないかという全体像をとてもよく理解できました。

youtu.be

エンジニア留学が決まったとき、何から手をつければいいのかわからず、勉強しておくといいと言われたものを手あたり次第に学び始めていました。あとからこのロードマップや解説動画に出会い、自分のやってきていたことがそんなにずれていなさそうで、ほっとしたのを覚えています。

また初学者にとって、自分の歩み方がずれていないか?という不安は日々ついてまわるので、学習のスタート時点でこういったロードマップがあると、とても安心だなと思いました。いつかfree初学者向けに、会計freeeの使い方やfreeeのAPIを叩くために必要な最低限の知識等をロードマップ にして公開してみたいです。

ロードマップ を眺めて立てた自己育成計画

下記はロードマップ とにらめっこし、1月〜12月にかけて立てた計画の一部抜粋です。

自己育成計画の一部抜粋。スプレッドシートに基礎的な内容から並べている

以降は、フロントエンドのロードマップにそって、どのように学習したかをご紹介します。

Internetについての学習

APIチームのマネージャーから年末に冬休みの宿題として、『Real Word HTTP』を紹介され、PdMのマネージャーからは『Webを支える技術』を紹介してもらいました。 しかし、いずれも読むための知識が圧倒的に足りなくて、音読はできるが理解ができない状態に陥ってしまいました。 そのため、もう一段レベルを下げて、『Web技術の基本』という文系の人向けにわかりやすくしてくれていそうな本を見つけたので、この本からまず入って学習を進めました。

HTML,CSS,JavaScriptの学習

この領域は、ドットインストールとYouTuberのしまぶーさんの動画で学習を進めました。 各領域はドットインストールは抜け漏れなく学習できるので、ざっと1回勉強をして、実践でじゃんけんアプリなどを作って、わからないことが出た場合は2回目を2倍速で見るという感じで活用していました。 ドットインストールは受講を終えていくとどんどん緑の棒が長くなっていき進捗がわかるので楽しかったです。

ドットインストールのキャプチャ

一方でドットインストールだけでは全体像や技術の背景・現在の開発現場でどこまで使われているのかなどはわからなかったので、そのあたりはしまぶーさんによる解説動画を見て理解していきました。もはやモダンな開発ではCSSや素のJavaScirptは書かないという事実は動画を見るまで知らなかったので、出会ってなかったらひたすらCSSを特訓していたかもしれません。3ヶ月の学習時間の配分を見誤らないかったのはしまぶーさんのおかけでした。

youtu.be

バージョン管理システム(GitHub,Git)

この領域については、Udemyの「Git:はじめてのGitとGitHub」で学習しました。

freeeで使われている方法についてはAPIチームのエンジニアのまっつーさんからレクチャーを受け、会計freeeのコード修正・プルリクエスト作成の実践学習を通して理解を深めました。

www.udemy.com

パッケージマネージャーとビルドルール

この領域については、YouTuberのしまぶーさんの動画で学習を進め、パッケージマネージャー・webpackの誕生の背景をざっと理解しました。

youtu.be

フレームワーク(React,Angular,Vue)

freee公式アプリはReactを採用しているので、まずはReactに限定し、学習を進めました。 この領域はじゃけぇさんのUdemyの「モダンJavaScriptの基礎から始める挫折しないためのReact入門」を用いて、JavaScriptの基礎を復習しつつ、Todoアプリを作成しながら学習しました。

www.udemy.com

axiosについては、YouTuberあべちゃんのReact入門をもとに、JSONPlaceholderやpixabayを用いてAPI通信の学びを深めました。

youtu.be

以上、自己育成計画をベースに学習した内容のご紹介でした。

FirebaseでReactを用いてアプリを作る基礎力は徐々についてきたので、引き続きTypeScriptを学び、いつか個人としてfreeeアプリストアでアプリをリリースすることを夢見て技術力をさらに上げていきたいと思っています。

来週は自分が対応した公式アプリの不具合の修正や機能拡張が続々とリリースされるのでとても楽しみです。

エンジニア留学はあと残り2週間!最後まで駆け抜けます!

Docker image を導入して protobuf を使う

こんにちは、会計freeeの開発をしている清水です。2020年4月に新卒としてfreeeに入りもうすぐ一年が経とうとしています。

この記事では私の所属チームのプロジェクトで試している、protobuf のための開発環境について書きます。

背景

現在私たちのチームでは、会計freeeのバックエンドのアーキテクチャ移行を進めています。会計freeeは長年にわたって開発が続けられているRailsアプリケーションです。現在でも社内の多くのチームのエンジニアが開発に関わっています。そんな中で実装は複雑化し、機能ごとの依存関係が分かりづらい状態になっていました。新しいアーキテクチャの目的は、そんなアプリケーションの実装の依存関係を明確にし、より安心して開発を継続できるようにすることです。

このあたりのより詳しい話は以前id:mihyaeru21が発表した以下の資料にまとまっています。

speakerdeck.com

現在移行を行っている範囲では、アーキテクチャ移行の第一段階として API Model と呼ばれる新たなインターフェースを導入しました。これは ActiveRecord に依存しないデータ構造で、バックエンドの実装内部において、モジュール同士は基本的にこのAPI Modelを介してのみやり取りを行うような設計になります。

現在のところ API Model の実装には、protobuf を採用しています。型が定義できること、また将来的に機能をマイクロサービスとして切り出す際もインターフェースとしてgRPCでそのまま流用できることがメリットです。

自動生成のためのコンテナ

API Model には protobuf を利用するため、Rails アプリケーションで実行される Ruby コードは、proto ファイルの定義から自動生成します。また読みやすい HTML 形式のドキュメントも、protoc のプラグインである protoc-gen-doc を使って、コードと一緒に定義から自動生成します。これにより常に実際に動くコードに連動してドキュメントが更新されるようになります。

例えば入力となる proto ファイルの定義と、自動生成される Ruby のコードと HTML のドキュメントは以下のような対応関係になります。

syntax = "proto3";

// コメント1
message Hoge {
  int64  number = 1; // コメント2
  string code   = 2; // コメント3
}
...
Google::Protobuf::DescriptorPool.generated_pool.build do
  add_file("sample.proto", :syntax => :proto3) do
    add_message "Hoge" do
      optional :number, :int64, 1
      optional :code, :string, 2
    end
  end
end

Hoge = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("Hoge").msgclass

protoファイルから生成されるドキュメント
生成されるドキュメント(protoファイルのコメントも反映される)

開発にあたっては、エンジニアごとのローカル環境に依存して生成物に差が生まれないようにする仕組みを用意する必要がありました。そこで自動生成のためのツールのバージョンや、実行環境を固定するためにDocker imageを利用し、Amazon Elastic Container Registry (ECR) を介してそれを開発者間で共有するようにしています。

Dockerfile はだいたい以下のような感じになり、build 時に使用する protocと proto-gen-doc のバージョンを指定します。

FROM debian:buster-slim

ARG PROTOC_VERSION
ARG PROTOC_GEN_DOC_VERSION

ADD https://github.com/google/protobuf/releases/download/v${PROTOC_VERSION}/protoc-${PROTOC_VERSION}-linux-x86_64.zip ./
ADD https://github.com/pseudomuto/protoc-gen-doc/releases/download/v${PROTOC_GEN_DOC_VERSION}/protoc-gen-doc-${PROTOC_GEN_DOC_VERSION}.linux-amd64.go1.15.2.tar.gz ./
RUN apt-get -q -y update && \
  apt-get -q -y install unzip && \
  unzip protoc-${PROTOC_VERSION}-linux-x86_64.zip -d ./usr/local && \
  tar xvzf protoc-gen-doc-${PROTOC_GEN_DOC_VERSION}.linux-amd64.go1.15.2.tar.gz && \
  cp protoc-gen-doc-${PROTOC_GEN_DOC_VERSION}.linux-amd64.go1.15.2/protoc-gen-doc ./usr/local/bin && \
  ...

# 生成物を手元に得るためのマウントポイント
VOLUME ["/ruby", "/docs", "/proto"]

ENTRYPOINT [ "protoc" ]

手元に落としてきた Docker イメージからコンテナを起動し、ローカルの proto ファイルから、コンテナ側でコードとドキュメントを生成します。最後にこの流れ実行できる Rake タスクを用意すれば開発環境の準備は完了です。

以上で開発者の環境による差分を気にすることなく、インターフェースの定義にだけに集中して開発が進められるようになりました。

低カロリーにスクラムマスターを始める方法

こんにちは、freeeで人事労務freeeを開発している id:gn-spawn です。 『シン・エヴァンゲリオン劇場版𝄇』面白かったですね。 パンフレットには制作スタッフのインタビューが記載されていて、感動した作品を作っている側の仕事術が読めるのはとても貴重で奮い立たせられました。

それはそうと最近スクラムマスターになったので、プロセスの改善を行った話を書いていきます。

スクラムマスターを引き継ぎという形で始めた

freeeでは多くのチームがアジャイル開発のプロセスを使ってプロダクトの開発を行っています。 私の所属するチームも1週間でスプリントを区切ったアジャイル開発を採用しています。 他の会社や組織では専任のスクラムマスターがいる場合もありますが、弊チームではスクラムマスターはエンジニアと兼任で行っています。

私のチームでは以下のような流れで開発を進めています。

小さいリリースと検証・改善を繰り返す
小さいリリースと検証・改善を繰り返す

スクラムを実施するにあたってチームでやっていることは以下のとおりです。

  • 毎朝のデイリーミーティング
  • スプリントレビュー
  • レトロスペクティブ
  • プランニング

なぜスクラムマスターになったのか

マネージャーとの1on1の中で

  • スクラムマスターのマネージャーが非常に忙しそうなので、自分が一部でも引き継げる部分はないか
  • プロセスの改善が好きなのでそういった領域で引き継ぎたい

という話をしていると、「スクラムマスターをやってみないか」と提案されました。 今までもスクラムでの開発経験はあるものの、自分でオーナーシップを持って運用したことはありませんでした。 色々な人とコミュニケーションを取るのが好き、少しでもマネージャーから委譲できればというモチベーションで挑戦してみました。

引き継ぐにあたってやったこと

まずはデイリーミーティングのファシリテーションから引き継ぎました。 前述のモチベーションから徐々に引き継いでいく方法を取りました。私がスクラムのオーナーに慣れていないというのも理由の一つです。

やり方を知らなかった私は、前スクラムマスターのやり方をそのまま行いました。

実際に感じた問題

全ての引き継ぎを行ったところ、思ったよりも時間が取られることが分かりました。 エンジニアとスクラムマスターが兼任なので、準備に時間が取られて思うように実装の時間が取られたりしてしまいました。

これは単に私が不慣れな部分があるのですが、実装の時間が取れないのはチームメンバーへの負担も増えますし、リリースしたい機能の開発も遅れてしまいます。

特に時間がかかっているのは

  • バックログの整理
  • バーンダウンの更新

の2点です。「スクラムマスター」のロールをやる以上はチームメンバーが迷わないように完璧な準備が必要だと思いこんでいました。

他チームを見て改善していく

まず問題の改善を行う場合に、スパッと「ここが今のやり方だとマズいよね」と分かれば一番なのですが知識や経験が無いとなかなか難しい部分です。 そこで先ずは他のチームのスクラムイベントを見学してみることにしました。

今は感染症対策もあり、ほとんどのエンジニアチームがオンラインでミーティングをしているので気軽に見に行けるのは助かりました。 その中から自分たちのチームにフィットするやり方を見つけて、取り入れていくことで改善しています。

実施したアクション

他チームのスクラムイベントを見学して、以下のことを実施しました。

  • バックログを整理しない
    • プランニングで整理もメンバーと一緒に行う
  • 準備の委譲
    • メンバーのスプリントごとに出した成果を自分で書いてもらう
    • バーンダウンもとりあえず準備してツッコミがあればその場で直す

スクラムマスターとしてちゃんと準備をしなくては。と思っていたせいで準備に時間がかかっていました。 しかし、メンバーを信頼して完璧に準備をすることをやめてみました。 その結果、精神的負担が減って漫然とした多忙さを感じることがなくなり、プロセスの改善にフォーカスできるようになりました。

得られた結果

スクラムイベントの最後に、感想や改善案を書けるアンケートを置いています。レトロスペクティブでそういうのはやれば良いのでは?とも思いましたが、 レトロスペクティブでは開発に関することにフォーカスを当てています。 私へのアンケートとして匿名も可能な形で書いてもらうことで、フィードバックを受けやすい形にしています。

プロセスの改善にフォーカスできるようになったおかげで、チームとしてより良いやり方を試行錯誤ながら追求しています。

まとめ

スクラムマスターに挑戦して一番のメリットは、プロジェクトの全体像を意識してオーナーシップを持てるようになったことです。 ユーザーに素早く価値を届けるにはどうしたら良いか?というのは、「頑張ってコードを書く」という単純なものではないと思っています。 職種に関わらず、プロダクトに関わる人全員を巻き込んで進めていくのはエンジニアだけで進めたときに見えないものが見えるので非常に面白いです。

会計フリー Public API史上初の新バージョン移行を完遂しました

こんにちは、freeeのPublic APIチームでエンジニアをしているまっつーです

花粉症ですごい鼻水が出るので少しくらい体重落ちてるんじゃないかと期待してます

去年の6月15日、会計freeeのPublic APIは新バージョンを公開しました

developer.freee.co.jp

この新バージョンでは約30個の破壊的変更を含んでいます

そして去年の12月、会計freeeのPublic APIは半年間の並行運用期間を経て、新バージョンへの完全移行を達成しました

この記事では後方互換性を保ち、既存ユーザーに影響を与えないことと、APIの負債を解消しより使いやすいAPIへと進化させることを両立するために、どのように工夫して進めたのかをお伝えしたいと思います

破壊的変更とは

Public APIはそれを使って開発や業務を行っている方がいるため、変更する時には後方互換性を担保しすべての利用者の動作に影響がないように行わなければなりません

しかし、会計freeeの機能拡充による変化や、過去に作った仕様が今現在では最適なものとは言えなくなくってしまったなどの理由から、後方互換性を担保しない変更を行わざるを得ない場合があります

freeeの場合はPublic APIを利用してアプリを作成しfreeeアプリストアに公開している開発者もいるので、後方互換性がない (今まで通りのリクエストを送信しても返ってくるレスポンスが異なる)ということは公開しているアプリが突然動かなくなるという事態につながります

この後方互換性を担保しない変更を破壊的変更と呼び、破壊的変更を実現するためにPublic APIでは並行運用期間を設けるという方法が取られることが多いです

また、上で述べたようにPublic APIはそれを使ってアプリを公開している開発者もいるので、新バージョンの公開には外部との連絡、連携が必須です

開発者には並行運用期間中に、利用しているAPIのバージョン移行をしてもらう必要があります

外部とのコミュニーケーションについては同じAPIチームでディベロッパーリレーションを担当しているニックさんが記事を書いてくれているので、ぜひそちらも読んでみてください

https://developers.freee.co.jp/entry/how-to-make-a-communication-plan

新バージョン移行への流れ

2020年1月頃: 変更点のスコープ整理とversioningの方法の検討

新バージョン公開の半年前からプロジェクトはスタートしました

目標を設定する

まず、今回の新バージョン公開で実現したいこと (目標)を決めました

以下の2点です

  • Public API Releaseからここまでのフィードバックおよび利用しにくい個所の改善(レスポンスの構造が他と異なる、freeeの権限がうまく効いていないAPIの改修など)を行い、開発者が速く安く手戻りなく作れるおよび使いやすいAPIになっている

  • インパクトを受けないアプリは改修アクションを行わなくても新しいバージョンに移行ができる(特定の日をもって自動切り替え)

スコープを整理する

次に新バージョンに盛り込みたい破壊的変更リストの整理を行いました

それまでユーザーからフィードバックをもらっていたものをメインに、具体的にどのエンドポイントのどこをどう直すかという点を確定していきました

新バージョンの表現方法、指定方法を決める

新バージョンを公開するにあたって

  • バージョニングポリシーをどうするか
  • バージョン指定方法をどうするか

という問題がありました

前提として、それまで会計freeeのPublic APIはバージョンいくつとはリファレンス上で明記しておらず、pathは api/1/{リソース名} となっていて「バージョン1 っぽいけどどこにも書いていない」という状態でした

バージョニングポリシーをどうするか

  • 案1 incrementalに増やしていき、次の新バージョンをv2とする

    • 現在 api/1 というpathになっているので旧バージョンをv1、新バージョンをv2、今後リリースされるものはv3とincrementalに増やしていく案
    • TwitterのAPIはこの手法をとっている
    • 良い点: 直感的にわかりやすい
    • 悪い点: バージョンの指定方法についての部分でも触れるが、バージョン指定方法をpath以外にした時、pathは /1 だけどバージョンはv2という状況がおこる。一方バージョン指定方法をpathで指定する (新バージョンのpathを /api/2 とする)と全てのAPIが新バージョン移行対象となり、既存で動いている全アプリでエンドポイント移行が必要になり、目標の2つ目が達成できなくなる
  • 案2 日付で表現

    • 新バージョンのリリース日をバージョン名とする案
    • StripeのAPIはこの手法を取っている
    • 良い点: pathが api/1 の状態を維持したまま新しいバージョンのリリースが出来る
    • 悪い点: 良い点と表裏一体だが、バージョン指定方法をpath以外にした場合、api/1 というpathのまま今後バージョンを上げていくことになる

バージョン指定方法をどうするか

  • 案1 pathで表現

    • 現在 api/1 となっている1の部分を新しいバージョン名に変える案
    • 良い点: ユーザーからするとどのバージョンのAPIを使っているかわかりやすい
    • 悪い点: 新バージョンで変更が加わるAPIを使っていないユーザーにも影響がある。内部的にも仕様変更がない部分は別々のパスからくるリクエストを同じコードで処理するなど複雑さが増す
  • 案2 アプリ管理画面から指定

    • freeeのAPIはアプリを作成してアクセストークンを取るので、アプリ管理画面で利用するAPIのバージョンを切り替える案
    • 良い点: 画面から決めることが出来るので設定が容易
    • 悪い点: UIが必要なので他の案より工数が多くかかる
  • 案3 ヘッダーで指定

    • 新バージョンを識別するX-Api-Version のようなカスタムヘッダーを用意して、ヘッダーがある時は新バージョン、ない時は旧バージョンの動きをする案
    • 良い点: 実装は比較的容易
    • 悪い点: バージョンの指定に多少の技術的なスキルが必要。freeeのAPI利用ユーザーにはエンジニアでは無い会計士さんのような方もいるのでこの点は意識して議論しました

結論 目標を考慮して、インパクトを受けないアプリは改修アクションを行わなくても新しいバージョンに移行ができるために、バージョニングポリシーについては案2の日付でのバージョン表現、バージョン指定方法は案3のヘッダー指定にし、リリース後様子を見てアプリ管理画面での指定の実装も検討するという結論になりました

(リリース後、既存アプリケーション開発者による移行状況から、headerでの指定による手段で移行要件が満たせていることがわかり、今回はにアプリ管理画面でバージョン指定ができるようにする実装は見送りました)

2020年3月頃: 新バージョンリリースに向けたリリースプランニング

実現方法が明確になったので、2月あたりからリリースに向けたプランニングを行いました

とりあえず大まかにどれくらいかかりそうかという見積もりを行い、PMやビジネス側のメンバーとも話し合ってリリース日を2020年6月15日に決定しました

この時点で新バージョンが Version: 2020-06-15 に決定しました

現在公開されている会計freeeのPublic APIのリファレンスにも大きくバージョン名が記載されています

会計freeePublic APIリファレンスのスクリーンショット。一番上に会計APIリファレンス Version: 2020-06-15と記載されている

2020年4月頃: バージョン切り替えの仕組み、新旧両バージョンでrequest validationを行うための実装

バージョン切り替えの仕組みの実装

4月頃から実装を開始しました

まずポイントになったのが「ソースコード上どこで新旧どちらのバージョンを指定してリクエストしてきたかを判別するか」です

前提として、会計freeeはRuby on Railsを利用しています 話し合った結果、もともと会計freeeに導入されていたrequest_storeというgemを利用することにしました

https://github.com/steveklabnik/request_store

簡単に説明すると、request_storeを使うことでrequestごとにglobalな変数を設定することができます

新バージョンを利用する際には X-Api-Version: 2020-06-15 をつけてもらう仕様としたので

requestが送信されるたびに、request_storeで

  • headerがあれば新バージョン

  • headerがなければ旧バージョン

であることを表す値を version という変数に代入します

これを各controllerやserializerなどで参照することで、新旧どちらのバージョンの挙動にするかを判定できるようにしました

新旧両バージョンでrequest validationを行うための実装

会計freeeのPublic APIではcommitteeというgemを利用してrequest validationを行っています

https://github.com/interagent/committee

このgemはOpenAPI Specificationに準拠したschemaを読み込ませることで、schemaにあわせたvalidationを行ってくれるものです

committeeは以下のようなやり方でschemaをしていた上でRackに入れて使用します

use Committee::Middleware::RequestValidation, schema_path: 'docs/schema.json', coerce_date_times: true

ただ複数のスキーマを読み込めるような仕様にはなっていないのでそのままでは新旧両バージョンでvalidationを行うことができませんでした

チーム内で相談した結果、RequestValidation層を2層挟み、またスキーマバージョンを判定する変数を渡せるようにしました

それぞれの層で上で書いたversionという変数を参照し、自らの対象バージョンでなければそのまま下位のRack層にrequestを流す方法を取りました

use Committee::Middleware::RequestValidation, schema_path: 'docs/old_schema.json', pubilc_api_version: 'v1'
use Committee::Middleware::RequestValidation, schema_path: 'docs/old_schema.json', pubilc_api_version: 'v2020-06-15'

このようにしてどちらのバージョンでもrequest validationを行えるようにしました

2020年5, 6月頃: 実際の破壊的変更対応を実装

バージョンを判定することができるようになったので、あとは 1月に決めたスコープの破壊的変更をガシガシと実装していきました

ただものによっては仕様が複雑でスッと実現できないものも多くありました

APIチームはエンジニア5人ほどで会計、人事労務の全エンドポイントを担当しているので全てのAPIを完全に把握するのは正直不可能です

そもそもこれは会計ソフトとして正しいんだっけ?みたいな部分はドメインロジックを担当しているチームに相談しながら実装を進めていきました

2020年6月15日: 新バージョンリリース!!!!!

バージョン名に日付が入っているので遅れると相当カッコわるいぞというプレッシャーがありましたがなんとか間に合わせることができました

並行運用期間

6月から12月までの並行運用期間は大きな出来事はありませんでしたが以下のことには気をつけていました

  • 細かな修正があったときに忘れずにAPIリファレンス含め、新旧両バージョン変更を加えること

あたりまえなんですが地味に見落としが多く、僕自身もプルリクエストのレビュー時に何度も指摘し、された覚えがあります

たった2つのバージョンを並行運用していても意識から漏れてしまうことがあったので、複数バージョンサポートとなった場合なにかしらの仕組みで自動で反映されないと厳しそうだなと感じました

また、この期間エンジニアはあまりやることはなかったですがビジネス側のメンバーはいろいろと働きかけてくれていました

  • 移行対象のエンドポイントのrequest数を確認して移行状況のチェック
  • freeeのdeveloper community参加者への全体連絡
  • freeeアプリストアに公開されているアプリのうち、移行対象のエンドポイントをつかっているアプリのオーナーに対して別で連絡

12月に無事旧バージョンのサポート廃止ができたのは間違いなくビジネス側のメンバーのおかげです

APIの新バージョンはエンジニア、ビジネス全員が一丸となって取り組まないと実現できないんだなと身をもって感じました

以上のことを乗り越えて、会計freeeのPubilc APIは現在新バージョンで稼働しています

興味のあるかたはぜひdeveloper siteから確認してAPI callしてみてください

freee Developers Community | freee Developers Community