APIを外部公開するまでの道のり
Showcase Gig Advent Calendar 2022 22日目の記事です。
こんにちは、Showcase Gigの中島(@ahyataro)です。
去年のアドベントカレンダーでは、 O:der Platformの立ち上げ初期に、どういったプロセスで自分たちの作るものを明確にしていったのかについて書きました。
あれから1年が経ち、O:der Platformは順調に成長を遂げ、次のステージであるAPIの外部公開にまで至りました。
今回はO:der PlatformのAPIを外部公開するまでにやったことを紹介します。
O:der Platformの構成
弊社では「O:der Table」, 「O:der Kiosk」, 「O:der ToGo」といった複数のプロダクトを開発しています。
これらは「Platform Core」という共通の基盤システムにつながっています。
エンドユーザーが注文するとCoreに注文が渡され、「Instore」, 「POS連携」というサービスを経て飲食店に届けられます。
Platform Coreは 注文・会計・決済といった汎用機能と、店舗・メニューなどのマスターデータ管理機能を持っており、 プロダクト開発の高速化やデータの一元化を目的としています。
なぜ外部公開するのか？
私達は、モバイルオーダーが世の中に浸透し、当たり前になっている世界を目指しています。 そのためにはより多くのお店に導入され、より多くの人に使われる必要があります。
飲食領域は、食事の提供方法が多岐にわたります。 弊社ではテイクアウトとイートインプロダクトを開発していますが、そのほかにもデリバリやドライブスルーなど様々な提供態があり、今後新たなものが生まれる可能性もあります。
お店側のオペレーションについても目を向けなければなりません。 飲食店では以下のオペレーションを経て、お客様に食事が提供されます。
フロアオペレーション
接客関連のオペレーション
キッチンオペレーション
調理関連のオペレーション
バックヤードオペレーション
在庫管理や事務処理などのオペレーション
飲食店側としてはオペレーションの破綻はクリティカルな問題であり、「お客様にとって便利なのはわかるけど、うちのオペレーションには合わないな...」と思われてしまうと、導入していただくことができません。 店舗オペレーションは業態ごとに異なるので、さらなる難しさを生んでいます。
O:der Platformは多種多様な提供態や店舗オペレーションに答えうるプラットフォームとなるために、 多くのパートナー・デベロッパーに対してAPIを開放し、あらゆるシステムと連携することで実現しようと考えています。
※ 現段階では、開放と言っても不特定多数の人たちに広く公開するのではなく、限られた開発パートナーに対しての公開までをスコープとしています。
外部公開を見据えて初期設計時に考えたこと
Coreの立ち上げ当初から将来的な外部公開を見据えて設計していました。
複数のユースケースを実現できるシンプルで汎用的な機能
O:der Platformにとって「注文」はコアな機能ですが、ひとえに注文と言っても、テイクアウト、イートインでかなり相違があります。
Coreではテイクアウト、イートインといった特定のユースケースに特化した機能は持たず、 注文・会計・決済というプリミティブな機能に分解することで、組み合わせ方次第で様々なユースケースを実現できるようにしています。
こういった設計をしておくことで、内製プロダクト特有の知識を含んでいない汎用注文APIを外部公開できました。
Coreは何者にも依存しないように
プロダクトから渡された注文は、CoreからInstoreに伝わり、店内機器に届けられます。 これらは分散サービスとなっているので、API呼び出しによる連携が必要になるのですが、 Instore側で定義したAPIをCoreから呼び出すという構成にすると、CoreからInstoreへの依存関係ができてしまいます。
連携サービスに依存してしまうと、サービスが増えるたびにCoreへの実装が必要となります。 特に、注文の通知をトリガーにして処理を行いたいサービスは多いので、外部公開して連携サービスが増えたときに障壁となってきます。
それを避けるためにCoreにはWebhookのしくみを用意しています。
Core側でWebhook通知のAPIスキーマを定義し、通知を受けたいサービス側でスキーマに従ってAPIを実装してもらうことで、 依存関係が逆転し、Coreが外部サービスに依存しなくていいようになります。
これにより新たな外部サービスと連携したい場合は、コードの改修を入れなくても通知先のURLを追加するだけで対応可能になりました。
依存関係を間違えてしまうとプラットフォームのスケーラビリティの障壁となってしまうため、設計初期からできるだけCoreは何者にも依存しないように気を付けてきました。
外部公開する際にやったこと
「さあ外部公開をやっていこう！」というフェーズで、 以下を実行しました。
認証認可基盤の構築
APIゲートウェイの構築
外部公開用のドキュメント整備
外部デベロッパー用開発環境(sandbox環境)の構築
認証認可基盤の構築
複数の外部クライアントに対してAPIを公開するなら、クライアントごとに適切なアクセス制御を行う必要があります。
これまではアクセストークンさえあれば、誰でも、どんな操作でもできてしまうという状況でした。 社内プロダクトしか使っておらず、一定の信頼関係が前提にあったため妥協できていましたが、外部システムに使ってもらうならそうもいきません。
きちんとした認証認可のしくみを整備する必要性を感じ、認証認可基盤の構築を決定しました。 専門性が高い領域であるため、専属のチームを組成し、オーナーシップを持って取り組めるように別サービスとして切り出しました。
「外部トークン」「内部トークン」「鍵の生成・管理」を主な責務とするSTS(Security Token Service)というサービスを開発し、柔軟なアクセス制御が可能になりました。
STSは、外部向けには外部トークン、内部向けには内部トークンをそれぞれ発行します。 外部クライアントは事前に発行したクレデンシャルを用いて、外部トークンを発行できます。 外部トークン付きのリクエストをすると、STSは外部トークンを内部トークンに変換します。 「クライアントがどのリソースに対して何の操作ができるか」といった設定をSTSは持っており、内部トークン生成の際にスコープ情報として埋め込みます。 プラットフォーム内部の通信では内部トークンが使われるため、各サービスは内部トークンに含まれるスコープ情報を元にアクセス制御を行えるようになりました。
APIゲートウェイの構築
STSを別サービスとして切り出したため、そのままだと利用側は既存のプラットフォームサービスとSTSの存在を意識しないといけなくなってしまいます。 APIゲートウェイを構築し、一層挟むことでプラットフォームをカプセル化し、クライアントはゲートウェイだけ意識すればいいようにしました。
参考: APIゲートウェイパターン
APIゲートウェイを導入したことで、部分的なAPI公開も簡単になりました。
既存のAPIは、すべてを公開できるほど磨き込まれてはおらず、内製のプロダクトのみが使うことを想定したAPIが多数存在するため、公開するものは一部のみにしたいという事情がありました。
APIゲートウェイでは外部公開用のAPIスキーマを別途定義しているので、公開したいものだけを絞り込んで公開できるようになりました。
まだ実践はできてないですが、APIの合成をしてクライアント側の呼び出し回数を減らす、といったことも可能になるため、今後のさらなる活躍に期待しています。
外部公開用のドキュメント整備
外部のデベロッパーにAPIを触ってもらうには、ドキュメントは必須です。
外部公開するにあたり、以下の2種類のドキュメントを整備しました。
概念的な説明やAPIの使い方についてのドキュメント
O:der Platformの全体感を把握してもらうためのドキュメントです。
O:der Platformとは何か？
どういった機能・データを提供しているか？
推奨のAPIの使い方
チュートリアル
などが書かれています。
ドキュメントはMarkdown形式で記述し、Docusaurusを使って、いい感じのドキュメントを生成しています。
Docusaurusについてはこちらの記事が詳しいです。
こういった自由記述型のドキュメントは存在を忘れられてメンテされなくなってしまいがちですので、 Markdownファイルをアプリケーションコードのリポジトリ内におき、コードの変更とともにドキュメントの変更も行いやすいようにしてます。
APIドキュメント
外部公開APIのI/Fを記述したドキュメントです。
APIゲートウェイで定義されているAPIスキーマから、redocを使って自動生成しています。
こちらはすべて自動生成されるのでメンテは非常に簡単です。
外部デベロッパー用開発環境(sandbox環境)の構築
外部デベロッパーが開発するときに、いきなり本番環境につないで検証、とするわけにはいかないので開発環境が必要です。
これまでも社内の開発者が使える開発環境はありましたが、品質担保されていないものがデプロイされるので、 社内の開発環境を外部デベロッパーに公開するわけにもいきません。
ということで、外部デベロッパー用の開発環境としてsandbox環境を新たに構築しました。
新機能や改修を本番環境よりも先にsandbox環境へ反映することで、外部デベロッパーが事前に開発を始められたり、変化に備えたりできるようになりました。
最後に
O:der PlatformのAPIを外部開発パートナーへ公開するまでにやったことについて紹介しました。
外部へのAPI公開の一例として少しでも参考になると幸いです。
外部公開の初期整備は完了しましたが、より安心して使ってもらえるように、 システムの安定性向上、sandbox環境・本番環境の安全な運用フロー構築などまだまだ課題は山積みです。
Showcase Gigでは、最高のプラットフォームを一緒に作る仲間を探しています！
今回の話で少しでもご興味を持っていただけた方はぜひご応募ください！
この記事が気に入ったらサポートをしてみませんか？