* 本記事は STORES Advent Calendar 2023 15日目の記事です
こんにちは。STORES ネットショップ のエンジニアをしております、takeuchiです。
STORES ネットショップ では2021年10月から開発者向けAPIを提供開始しました。
この記事では、APIリリースに至るまでに行われた検討事項について紹介します。
背景
2021年頃、以下の理由から開発者向けAPIの開発に着手することになりました。
- 外部連携によるサービス拡充を行いたい
- ネットショップの運用で不足している機能の開発をAPIを利用してユーザー自身が行える状態を目指したい
第一弾として、ネットショップの運用の中でも特に重要なデータである、オーダー(注文情報)を提供するAPIの開発に着手しました。
APIで提供する項目
まずはどのようなデータを出力するか考えなければいけません。
STORES ネットショップ のユーザーは、ネットショップの管理画面であるダッシュボードを利用します。 ダッシュボードに載せている項目は、ユーザーのネットショップの運用に日々利用されています。
このダッシュボードの項目を参考にAPIで出力する項目を検討しました。
STORES ネットショップ のオーダー詳細ページ
例として、オーダー情報のAPIでは、ダッシュボードのオーダーページにある全項目を取得できるようにしました。
その上で過去 STORES ネットショップ にユーザーから挙げられた要望の中で今後必要になってくるであろう項目も合わせて、提供する項目を決めていきました。
バージョンの管理方法
APIにバージョン管理がなければ、APIの変更が行われる度にクライアントアプリケーションに影響を及ぼす可能性があります。
運用中のクライアントアプリケーションとの互換性を保つために、バージョン管理を採用しています。
バージョンの指定方法
ユーザーがどのようにAPIのバージョンを指定するか考える必要があります。
パラメータやヘッダーでバージョンを指定する方法もありますが、URLパスにバージョン情報を含め、特定のバージョンに対応したURLをユーザーに指定してもらう方針で進めました。
https://api.stores.dev/retail/202109/orders
バージョンアップのポリシー
どのような場合にAPIのバージョンアップを行うが考える必要があります。 あたらしいAPIに変更が入るたびに毎回バージョンアップを行うとなると、APIのバージョンアップの頻度が高くなり、都度クライアントアプリケーションを運用しているユーザー側の対応が必要になります。
API運用側としてもAPIの変更のたびにユーザーへの通知が必要になるため、バージョンアップに関しては特定のケースに限定できないか検討しました。
そこでAPI運用側と利用側双方の運用負荷を軽減するため、バージョンアップはAPIとクライアントアプリケーションの互換性が保てないような破壊的な変更がAPIに入る時のみ、新規バージョンを追加することに決めました。
そのため、
のみの変更に関しては新規バージョンの追加は発生せず、APIレスポンスの項目名の変更や削除等の破壊的な変更を伴う場合のみ、あたらしいバージョンを追加することに決めました。
バージョンアップの対象
新規バージョンの追加では変更が加えられるAPIのみ新しいバージョンを用意するか、変更が入らない他のAPIもまとめて新しいバージョンを追加するかの検討も必要でした。
変更対象のAPIのみ新しいバージョンを追加してしまうと、APIごとに保持するバージョンが変わってしまいます。利用側もAPIごとにどのバージョンが利用可能かを意識しなければならず、提供側も管理が煩雑になってしまいます。
そのため、どれか1つのAPIに変更が入りバージョンの追加が必要な場合は全てのAPIのバージョンを上げることにしました。
APIドキュメントの公開
STORES ではスキーマ駆動開発を採用しており、APIを作成する際には OpenAPI のフォーマットに従ってAPI仕様をYAML形式でスキーマを書き出します。 開発者向けAPIの開発でも同様にスキーマを作成し、API仕様を管理しています。
APIドキュメントを1からデザインして作成するのは手間がかかるので、このスキーマを使いAPIドキュメントを作成しました。
当時社内で利用実績のあった redoc を使い、スキーマからhtmlファイルを作成します。このファイルを GitHub Pages で公開し、APIドキュメントをユーザーに公開しています。
最後に
今回は STORES ネットショップ の開発者向けAPIのリリースに向けて検討したことについて紹介しました。この他に書けていない部分もあるのですが、それはまた次回に紹介させていただければと思います。
2021/10にリリースされて以降、その後新規のAPIも追加され現在も運用されています。 まだまだ整備されていない部分があり、足りないものが多いので、引き続き使い勝手が良いものにしていけるように開発・運用の整備を進めていきます。
