APIライフサイクルとAPIOps

Shinichi Hashitani

---

API as a Product

API as a ProductとはAPIの設計、開発、運用を長期的な視点で捉えるアプローチです。APIとは利用される事により価値を提供出来るという資産であり、変わりゆく市場やユーザーのニーズをフィードバックとして受け止め、絶えず変化に追従する事が求められます。プロダクトとして扱われるAPIは、その利用者が社内/社外/パートナー企業であるかに関わらず、プロダクトマインドセットを持って運用することが成功要因の一つとなります。

プロダクトとして扱うことは、プロジェクトとして捉えるアプローチとは大きく異なり：

• 特定のスコープや期間における開発ではなく、恒久的な運用と変更管理が必要である。
• プロダクトにも始まりと終わりがあり、価値提供が出来なくなるとプロダクトは終焉を迎える。
• プロダクトの責任はプロダクトチームに帰属する。優先度の策定、リソース/予算配分の決定権もプロダクトチームの裁量で行う。
• KPIは主にプロダクトの利用満足度の向上をゴールとしたものとなり、利用継続/拡大に関わるものとなる。
• APIライフサイクル管理はプロダクトマネジメントの有機的な一部分であり、割く労力の肥大はプロダクト改善速度に直接的な悪影響を及ぼす。

API as a Productの思想は継続的かつ長期的な視野に立っており、プロダクトを利用する側のフィードバックを重要視するアプローチです。

API 開発サイクル マネジメント

プロダクトマインドセットが既に確立されているチームであれば、API as a Productの概念も至極自然なアプローチとして捉えることができます。その実践も開発/運用におけるDevOpsのプラクティスに沿わせる事により、効率よくかつ有機的に実践する事が可能です。

APIのライフサイクルは、小さなインクリメンタルプロセスの積み重ねで構成されます。日々のプロセスではアジリティを求められ、変化に強い文化とプラクティスにフォーカスが置かれています。この思想はDevOps文化の中核であり、継続的改善を素早く回すというアプローチもCI/CD パイプラインを利用する手法も同様です。

しかしながら、実際にはAPIの開発サイクルがDevOpsオペレーションに有機的に統合されているケースはあまり多くありません。APIプロダクトに関しては一貫性を欠いていたり、マニュアル作業やチェックが散見されたり、上手く噛み合っていない印象をよく受けます。

これはパイプライン上のタスクが抜けているという以上に、API as a Productという概念が希薄というのが根本原因ではないかと思います。APIプロダクトの視線でパイプラインを見直すと、APIプロダクト特有の必要なステップがいくつか浮かび上がります。

Collaborate

APIは組織の中で存在しているだけでは価値提供できません。利用されて初めて価値が生まれます。この為組織中のAPIは何かしらの形で定義が集約され、その定義は最新の状態に保たれ、ドキュメントとして自己完結している必要があります。またこれらAPIプロダクトを誰もが閲覧/検索出来、セルフサービスで利用できるポータル (Developer Portal) を提供することも重要です。

合わせて、それらAPIへアクセスする為のツールセット (PostmanやInsomniaにおけるRequest Collections) が共有され、利用者が効率的に利用できる配慮が必要です。いかにユーザーがAPIプロダクトを容易に見つけ、評価し、利用出来るかがCollaborateにおける重要指標です。

Ship & Engage

それぞれのAPIには複数のバージョンが存在し、ライフサイクルを通して新しいバージョンを足しつつ古いバージョンを提供停止にする必要があります。ユーザーのフィードバックを形として還元するには、その要望を新機能という形で還元する必要があります。どの機能改善要件を採用するのか、そして下位互換性のない変更 (メジャーバージョンアップ) をいつ導入するかは、ユーザーの声を元にフェアに判断する必要があります。

また、プロダクトチームにとって複数のバージョンを管理する事は大きな負荷であり、プロダクト開発のリソースをその維持に割く必要があります。古いバージョンの提供停止はユーザーにとっては大きな変更です。古いバージョンの提供停止にはユーザー利用傾向の正確な把握と、長期にわたる撤退戦略 (Decommissioning Strategy) が必要です。

Ship & EngageではAPIのバージョン追加/変更と、そのライフサイクルの推移をユーザーと共有する2つが密接に結びついている事を強調しています。常に変化する事が必要なAPIプロダクトは、その変化を実現するだけでなく、変化の過程をユーザーと共有し理解してもらう事も重要です。

APIOps

APIOpsとは、API as a Productの概念をDevOpsパイプラインに組み込むアプローチです。チームがAPIプロダクトの改善に集中出来るよう、DevOpsパイプラインにAPIプロダクトのタスクを埋め込み一貫性を高める事が目的です。端的に言うとプロセスの自動化でありオートメーションですが、このプラクティスをチームの常識としてプロセスの一環に捉える大きな効果があります。

APIOpsを達成するには、幾つかの新しいタスクをパイプラインに追加する必要があります。

• API定義のバージョン管理 – Open API Specを他のリソース同様バージョン管理します。またこのソースの変更自体がプロセスをキックするトリガーとなる。
• API定義変更のバリデーション – API定義変更に対するテストの実行、仕様チェック、その他チェックを実行し、パスした場合のみ次のステップに進む。
• API Gatewayの構成ファイル生成 – Open API Spec内に定義されたPathやServerといったオブジェクトを元にKongの構成ファイルを自動生成する。
• API Gateway構成変更の反映 – Open API Specと同期を取ったAPI Gatewayの宣言的な構成情報をAPI Gatewayに反映する。

Kongの場合、API定義とAPI Gateway定義を繋げるのにはInsomina CLI (inso) 、API Gateway定義の宣言的な反映にはdecK (deck)を利用します。これらを用いたパイプラインの全体像は以下のようになります：

Step 1: APIデザイン

Kong Insomniaはマルチプラットフォームで稼働するオープンソースの統合API開発環境です。Open API Specのエディターであり、仕様の文法チェック、デバッグ、ドキュメンテーション、テスト、Mockサーバーのデプロイまで幅広いAPI開発プロセス全体を支えます。Open API SpecはAPIにおけるSingle Source of Truthとなり、APIに関連する定義が集約されます。最終的な成果物はOpen API Specそのものであり、テスト等が完了した後には他のリソース同様Gitにてバージョン管理します。

Step 2: API Specのチェック

Insomniaでは通常利用するデスクトップアプリの他に、コマンドラインから利用できるクライアントも提供しています。API Spec自体はローカル環境でテストされていますが、スペックの一定水準の品質を保ちつつレビュー負荷を下げる為には、パイプライン上での自動チェックも必要です。InsomniaのCLIクライアント (inso) がその役割を担います。Open API Specの変更がプッシュされパイプラインのトリガーが実行される際、以下のコマンドを追加で実行します。

# API Specの文法チェック
inso lint spec openapi/my-service.yaml --ci
# テストの実行
inso run test uts_012d48 --env localdev --ci

Step 3: Kong Gatewayへの変更反映

バリデーション/テスト/レビューをクリアしたスペックから、次にKong Gatewayの構成情報を自動的に生成します。deckにはOpenAPI SpecからKong Gatewayの構成情報を出力するopenapi2kongというサブコマンドが用意されています。実行結果として出力されるyamlファイルは、Kong Gatewayのあるべき姿を宣言的に定義したものとなります。

# OpenAPI SpecからKongの構成ファイルを出力
deck file openapi2kong -s my-service.yaml
# Kong構成ファイルの宣言的な適用
cat kong.yaml | deck gateway sync --headers Kong-Admin-Token:kongstrong

decKには様々なコマンドがありますが、Kongの宣言的管理もその一つです。Kong Gatewayの定義を受け取り、対象となるKong Gatewayの構成情報を確認の上、差分を特定してそれを解消する為の変更をKong Gatewayにリクエストします。

まとめ

APIライフサイクルのゴールは、ユーザーに価値を提供し続ける事です。そのライフサイクルは日々の改善プロセスの積み重ねであり、そのプロセスには必ずユーザーとのコラボレーションが含まれます。DevOpsパイプラインは、API as a Productの概念に基づいて補完され、APIOpsとして成長する事でAPIライフサイクルを支える事ができます。