DEVELOP EFFECTIVE API © 2024, Amazon Web Services, Inc. or its affiliates. All rights reserved. © 2024, Amazon Web Services, Inc. or its affiliates. All rights reserved. 実践的にAPIを開発していく ソースコード管理とデリバリーを考えよう Daisuke Awaji Solutions Architect Amazon Web Services Japan Develop Effective Web API – versioning 編

DEVELOP EFFECTIVE API © 2024, Amazon Web Services, Inc. or its affiliates. All rights reserved. Daisuke Awaji Amazon Web Services Japan Solutions Architect 2 @gee0awa

DEVELOP EFFECTIVE API © 2024, Amazon Web Services, Inc. or its affiliates. All rights reserved. © 2024, Amazon Web Services, Inc. or its affiliates. All rights reserved. デリバリーの速度 3

DEVELOP EFFECTIVE API © 2024, Amazon Web Services, Inc. or its affiliates. All rights reserved. イノベーションループ 4 Listen Idea Experiment イノベーション ループ 傾聴 アイデア 実験

DEVELOP EFFECTIVE API © 2024, Amazon Web Services, Inc. or its affiliates. All rights reserved. "デリバリー速度"の獲得 • マイクロサービスの最大のメリットは ビジネス変化に対応する"デリバリー速度"の獲得 • でも API で作ったサービスは頻繁な変更に対応するのは難しい • なぜなら API にはインターフェース契約があるから • そこで、”疎結合” にマイクロサービス を組み立てる、 イベントドリブンアーキテクチャという手法もある • それでも API とは向き合っていく必要がある 5

DEVELOP EFFECTIVE API © 2024, Amazon Web Services, Inc. or its affiliates. All rights reserved. © 2024, Amazon Web Services, Inc. or its affiliates. All rights reserved. API で結合する 6

DEVELOP EFFECTIVE API © 2024, Amazon Web Services, Inc. or its affiliates. All rights reserved. アーキテクチャの結合度 7 小さなピースに分けて ゆるく結合させたい

DEVELOP EFFECTIVE API © 2024, Amazon Web Services, Inc. or its affiliates. All rights reserved. 小さなピースを API で結合してみる 8 API API

DEVELOP EFFECTIVE API © 2024, Amazon Web Services, Inc. or its affiliates. All rights reserved. 契約による結合 9 API API インターフェース契約 APIにはインターフェースを公開し 利用者に宣言する必要がある 利用者は公開者の宣言にしたがって 送信する義務を負う

DEVELOP EFFECTIVE API © 2024, Amazon Web Services, Inc. or its affiliates. All rights reserved. 互いに依存する 10 API API (API利用者) 契約を守らないと呼び出せない (API提供者) 契約を破棄できない 不自然な維持、冗長な拡張

DEVELOP EFFECTIVE API © 2024, Amazon Web Services, Inc. or its affiliates. All rights reserved. 仕様と実装の乖離が許されないAPI = 契約 11 • 契約を記述する手段の進化 • 契約の配布やスキーマレジストリ 管理のマネージド化 • ただし、契約は公開されるが、強制できる ものではない。 • そして、APIエコノミーへ • クローズドなAPIからオープンなAPIへ

DEVELOP EFFECTIVE API © 2024, Amazon Web Services, Inc. or its affiliates. All rights reserved. 多様化、複雑化、膨大化する依存関係 12 API 互いに依存する 互いに依存する

DEVELOP EFFECTIVE API © 2024, Amazon Web Services, Inc. or its affiliates. All rights reserved. 同期的な API の課題 • 他サービスの障害に影響を受ける • 障害影響範囲 • 依存関係の同時デプロイ • クライアントへの統一した体験が提供しにくい • HTTPリソースやメソッドごとに要件が複雑化 13

DEVELOP EFFECTIVE API © 2024, Amazon Web Services, Inc. or its affiliates. All rights reserved. API のバージョン管理の重要性 14 v1 v2 Client API の破壊的変更に対する Client への影響を最小化する 複数バージョンの API を同時稼働させ、Client ごとに異なるタイミングで新バージョンに移行させる Client Client

DEVELOP EFFECTIVE API © 2024, Amazon Web Services, Inc. or its affiliates. All rights reserved. バージョン情報の表現方法 15 v1 メジャーバージョン v1.2 メジャーバージョン マイナーバージョン v1.2.3 セマンティック バージョニング

DEVELOP EFFECTIVE API © 2024, Amazon Web Services, Inc. or its affiliates. All rights reserved. セマンティックバージョニング 16 https://semver.org v1.2.3 メジャーバージョン マイナーバージョン パッチバージョン APIの変更に互換性のない場合に上げる 後⽅互換性を伴うバグ修正をした場合に上げる 後⽅互換性があり、機能性を追加した場合に上げる

DEVELOP EFFECTIVE API © 2024, Amazon Web Services, Inc. or its affiliates. All rights reserved. バージョン情報の見せ方 17 1. URL バージョニング URL のパスパラメータでバージョンを指定する方法 例）/v1/users, /v2/users 2. ヘッダーバージョニング リクエストヘッダーでバージョンを指定する方法 例）Accept: application/json; version=1 セマンティックバージョニングを採用する場合、 必要に応じてマイナー・パッチバージョンを表現するために、さらにバージョン情報を返す API を実装する Client GET /version { “version”: “v1.2.3”, “updatedAt”: “2024-01-23” }

DEVELOP EFFECTIVE API © 2024, Amazon Web Services, Inc. or its affiliates. All rights reserved. © 2024, Amazon Web Services, Inc. or its affiliates. All rights reserved. API Gateway を使用して 複数バージョンの API を管理する 18

DEVELOP EFFECTIVE API © 2024, Amazon Web Services, Inc. or its affiliates. All rights reserved. API Gateway で複数バージョンを管理するパターン 19 v1 API Gateway v2 v2 v2 v1 v1 v1 v2 1. API Gateway の Stage を使用する 2. API Gateway の API 自体を分ける

DEVELOP EFFECTIVE API © 2024, Amazon Web Services, Inc. or its affiliates. All rights reserved. 1. API Gateway の Stage を使用する 20 Stage 変数を使用して、Stage ごとにリソースを割り当てる API Gateway v1 Stage v2 https://xxx.execute-api.region.amazonaws.com/v1 https://xxx.execute-api.region.amazonaws.com/v2 Client AWS Lambda v1 AWS Lambda v2 ステージ変数を使用して ダウンストリームのリソースを紐付ける /v1/users /v2/users arn:aws:lambda:::function:${stageVariables.}/invocations

DEVELOP EFFECTIVE API © 2024, Amazon Web Services, Inc. or its affiliates. All rights reserved. 1. API Gateway の Stage を使用する 21 構成が大きく変わる場合、Stage 変数では対応できないケースも API Gateway v1 Stage v2 https://xxx.execute-api.region.amazonaws.com/v1 https://xxx.execute-api.region.amazonaws.com/v2 Client AWS Lambda v1 AWS Lambda v2 ただし、メジャーバージョンアップに伴い、 ダウンストリームのリソース・構成が大きく変動する場合 ステージ変数による単純なマッピングでは複雑化、対応できないケースも /v1/users /v2/users /v2/companies ステージ変数を使用して ダウンストリームのリソースを紐付ける arn:aws:lambda:::function:${stageVariables.}/invocations

DEVELOP EFFECTIVE API © 2024, Amazon Web Services, Inc. or its affiliates. All rights reserved. 2. API Gateway の API 自体をバージョンごとに管理する 22 そもそも v1, v2 は似て非なる全く別のアプリケーション API Gateway prod Stage https://xxx.execute-api.region.amazonaws.com/prod Client AWS Lambda v1 AWS Lambda v2 API Gateway prod https://yyy.execute-api.region.amazonaws.com/prod v1 v2 API Gateway のカスタムドメインを使用して 独自ドメインを紐づける https://example.com/v1 https://example.com/v2 /v1/users /v2/users ステージ変数を使用せず、 各 API にそれぞれ接続先を設定する

DEVELOP EFFECTIVE API © 2024, Amazon Web Services, Inc. or its affiliates. All rights reserved. © 2024, Amazon Web Services, Inc. or its affiliates. All rights reserved. Infrastructure as Code との 相性を考える 23 全てのリソースを Infrastructure as Code で管理したい

DEVELOP EFFECTIVE API © 2024, Amazon Web Services, Inc. or its affiliates. All rights reserved. API Gateway を IaC 管理する要素 24 AWS CDK AWS CloudFormation または + または AWS SAM API 定義 REST API 定義の規格（OpenAPI）の宣言ファイル（YAML or JSON）と インフラコード管理のテンプレートである AWS CDK（または CloudFormation や SAM）を併用する

DEVELOP EFFECTIVE API © 2024, Amazon Web Services, Inc. or its affiliates. All rights reserved. const fn = new lambda.Function(this, ”Lambda", { runtime: lambda.Runtime.NODEJS_20_X, code: lambda.Code.fromAsset("lambda"), handler: "index.handler", }); const api = new apigateway.SpecRestApi(this, "users-api", { apiDefinition: apigateway.ApiDefinition.fromAsset("path-to-file.json"), }); API Gateway を IaC 管理する要素（実装イメージ） 25 API 定義 AWS CloudFormation または または AWS SAM paths: "/users": get: description: get users parameters: - name: name in: query required: false schema: type: string default: "World" responses: "200": content: "application/json": schema: $ref: "#/components/schemas/UsersResponse" x-amazon-apigateway-integration: type: "aws_proxy" httpMethod: "POST" uri: "arn:aws:apigateway:ap-northeast-1:lambda:path/2015-03- 31/functions//invocations" ファイル参照 AWS CDK

DEVELOP EFFECTIVE API © 2024, Amazon Web Services, Inc. or its affiliates. All rights reserved. API Gateway を IaC 管理する要素（実装イメージ） 26 API 定義 AWS CDK paths: "/users": get: description: get users parameters: - name: name in: query required: false schema: type: string default: "World" responses: "200": content: "application/json": schema: $ref: "#/components/schemas/UsersResponse" x-amazon-apigateway-integration: type: "aws_proxy" httpMethod: "POST" uri: "arn:aws:apigateway:ap-northeast-1:lambda:path/2015-03- 31/functions//invocations" const fn = new lambda.Function(this, ”Lambda", { runtime: lambda.Runtime.NODEJS_20_X, code: lambda.Code.fromAsset("lambda"), handler: "index.handler", }); const api = new apigateway.SpecRestApi(this, "users-api", { apiDefinition: apigateway.ApiDefinition.fromAsset("path-to-file.json"), }); API Gateway 配下に接続するリソース（AWS Lambda など）を宣言する が、実際は CDK で定義した Lambda を参照させたい

DEVELOP EFFECTIVE API © 2024, Amazon Web Services, Inc. or its affiliates. All rights reserved. OpenApiX 27 https://github.com/alma-cdk/openapix AWS CDK OpenAPI の定義から AWS リソースの依存関係を排除して、CDKに移譲する x-amazon-apigateway-integration が不要に CDK 側でパスとリソースの紐付けを記述

DEVELOP EFFECTIVE API © 2024, Amazon Web Services, Inc. or its affiliates. All rights reserved. API Gateway で複数バージョンを管理するパターン 29 v1 API Gateway v2 v2 v2 v1 v1 v1 v2 1. API Gateway の Stage を使用する 2. API Gateway の API 自体を分ける Infrastructure as Code で、どのようにデプロイしていくか？

DEVELOP EFFECTIVE API © 2024, Amazon Web Services, Inc. or its affiliates. All rights reserved. 1. API Gateway の Stage を使用する 30 API Gateway の定義の宣言は１つとなるため、ダウンストリームのリソースも 同じコードベースで管理した方が都合が良いケースが多い API Gateway v1 Stage v2 https://xxx.execute-api.region.amazonaws.com/v1 https://xxx.execute-api.region.amazonaws.com/v2 AWS Lambda v1 AWS Lambda v2 /v1/users /v2/users GitHub main branch デプロイの最小単位（スタック） AWS CDK AWS CloudFormation AWS SAM Open API Spec など deploy

DEVELOP EFFECTIVE API © 2024, Amazon Web Services, Inc. or its affiliates. All rights reserved. 2. API Gateway の API 自体をバージョンごとに管理する 32 API Gateway prod Stage https://xxx.execute-api.region.amazonaws.com/prod AWS Lambda v1 AWS Lambda v2 API Gateway prod https://yyy.execute-api.region.amazonaws.com/prod v1 v2 https://example.com/v1 https://example.com/v2 /v1/users /v2/users Git のブランチ（あるいはリポジトリ）単位で、デリバリのパイプラインを分けることが可能に v1, v2 は全く異なるアプリとなるため、別物として管理した方が都合がいいケースも GitHub v1 branch deploy GitHub v2 branch deploy デプロイの最小単位（スタック）

DEVELOP EFFECTIVE API © 2024, Amazon Web Services, Inc. or its affiliates. All rights reserved. ここまでのまとめ 34 • API Gateway の Stage を使用してバージョンを管理する § シンプルに構成を大きく変えずにデリバリする場合は有効となりうる § 複数チームが独立し、デリバリのパイプラインが分かれるシーンでは不向き • API Gateway の API 自体をバージョンごとに分けて管理する § 構成が大きく変わる場合でも対応しやすい § ダウンストリームの構成のデリバリを分割しやすい

DEVELOP EFFECTIVE API © 2024, Amazon Web Services, Inc. or its affiliates. All rights reserved. © 2024, Amazon Web Services, Inc. or its affiliates. All rights reserved. そのメジャーバージョン、 本当に必要ですか？ 35

DEVELOP EFFECTIVE API © 2024, Amazon Web Services, Inc. or its affiliates. All rights reserved. バージョンアップ・リリースの実際 36 • パッチ・マイナー・メジャーバージョンの順番に更新頻度が多い • パッチ・マイナーバージョンアップでは、 Client に影響を与えずに無停止でシステムを更新できる • メジャーバージョンが変わる（破壊的変更を伴う）シーンでは、 Client への影響を考慮して、v1・v2 を並行稼働することが求められる § Client が１つのアプリ（例えば Frontend の React アプリ）だけだとしたら？ § 結局システムのダウンタイムを許容していいシーンだったら？ これらの場合、そもそも v1・v2 という考え方すら不要になるのでは

DEVELOP EFFECTIVE API © 2024, Amazon Web Services, Inc. or its affiliates. All rights reserved. © 2024, Amazon Web Services, Inc. or its affiliates. All rights reserved. モデルケース１ SPA (React) + API Gateway 37 破壊的変更を伴うが、システムのダウンタイムを許容するケース

DEVELOP EFFECTIVE API © 2024, Amazon Web Services, Inc. or its affiliates. All rights reserved. SPA (React) + API のリリース手順 38 Amazon CloudFront Amazon S3 Amazon API Gateway v1 AWS Lambda v1 Client Frontend Repository Backend Repository デプロイの最小単位（スタック） CDK + React CDK + Backend Logic HTML CSS, JS 初期状態では Client (ブラウザ) では v1 の Frontend アプリが稼働しており v1 の API に対して動作する v1 v1 必ずしも CDK である必要はありません。 CloudFormation, Terraform などでも同様の 考え方となります。

DEVELOP EFFECTIVE API © 2024, Amazon Web Services, Inc. or its affiliates. All rights reserved. SPA (React) + API のリリース手順 39 Amazon CloudFront Amazon S3 Amazon API Gateway v1 → v2 AWS Lambda v1 → v2 Client Frontend Repository Backend Repository デプロイの最小単位（スタック） deploy CDK + React CDK + Backend Logic HTML CSS, JS v1 STEP 1 Backend の API を v1 から v2 に更新する v1 の Frontend アプリは、 v2 の API に対して動作しないため、 リロードを求めるダイアログなどを表示する ※ バージョン情報を返す API パスを実装する必要があります ※ PUT, POST, DELETEなど更新操作を伴うリクエストを v1 の API に実行した瞬間に v2 API がリリースされた場合、 Frontend で例外をハンドリングする必要があります。 v1

DEVELOP EFFECTIVE API © 2024, Amazon Web Services, Inc. or its affiliates. All rights reserved. SPA (React) + API のリリース手順 40 Amazon CloudFront Amazon S3 Amazon API Gateway v2 AWS Lambda v2 Client Frontend Repository Backend Repository デプロイの最小単位（スタック） deploy CDK + React CDK + Backend Logic v2 HTML CSS, JS v2 STEP 2 Frontend の Contents を v1 から v2 に更新 ユーザはブラウザのリロードを行い v2 の Frontend Contents を取得し v2 の API と通信する

DEVELOP EFFECTIVE API © 2024, Amazon Web Services, Inc. or its affiliates. All rights reserved. モデルケース１ SPA (React) + API Gateway 41 • Backend の API は破壊的変更を伴うバージョンアップがあったものの、 Frontend の SPA アプリでブラウザのリロードを促すダイアログを表示することで システムダウンという印象をユーザに与えることなく、バージョンの更新を行うことができた

DEVELOP EFFECTIVE API © 2024, Amazon Web Services, Inc. or its affiliates. All rights reserved. © 2024, Amazon Web Services, Inc. or its affiliates. All rights reserved. パッチ・マイナーバージョンアップ 安定したデプロイを維持するために 42

DEVELOP EFFECTIVE API © 2024, Amazon Web Services, Inc. or its affiliates. All rights reserved. © 2024, Amazon Web Services, Inc. or its affiliates. All rights reserved. モデルケース２ API Gateway + NLB + ECS 43 破壊的変更を伴わない（パッチ・マイナーバージョンアップ）を行うバックエンド Infrastructure as Code とデプロイの単位をどう設計するか？

DEVELOP EFFECTIVE API © 2024, Amazon Web Services, Inc. or its affiliates. All rights reserved. API Gateway + NLB + ECS という黄金パターン 44 Amazon API Gateway API Gateway のプライベート統合を使って internal な NLB – ECS Service に接続する Web API Client Virtual private cloud (VPC) VPC Link Network Load Balancer Service ECS Fargate ※説明の簡単化のために、サブネットや冗長化などは一部簡略化して表記しています。 Internet (HTTPS)

DEVELOP EFFECTIVE API © 2024, Amazon Web Services, Inc. or its affiliates. All rights reserved. パッチバージョンアップする場合 45 Amazon API Gateway v1.0.0 API のインターフェース定義（リクエストパラメータやレスポンススキーマなど）が変わらず、 ECS Service として稼働するアプリのバグ改修など、パッチバージョンアップの場合を考える。 Client Virtual private cloud (VPC) VPC Link Network Load Balancer Service v1.0.0 ECS Fargate ※説明の簡単化のために、サブネットや冗長化などは一部簡略化して表記しています。 Internet (HTTPS)

DEVELOP EFFECTIVE API © 2024, Amazon Web Services, Inc. or its affiliates. All rights reserved. ECS Service で稼働するアプリケーション 46 例）ユーザ登録（POST /users）API の Service クラスのロジックにおいてバグがあった API のインターフェースの変更、データベースのスキーマ変更は伴わないケース Controller GET /users （ユーザ一覧取得） POST /users （ユーザ登録） getUsers() postUser(User) Service Model Database Logic Logic Client バグ例）Request Body に メールアドレスが無くても 登録できてしまう！

DEVELOP EFFECTIVE API © 2024, Amazon Web Services, Inc. or its affiliates. All rights reserved. パッチバージョンアップする場合 47 Amazon API Gateway v1.0.0 → v1.0.1 インターフェース変更、破壊的変更はないため、 API Gateway, ECS Service のどちらを先に更新しても問題はない Client Virtual private cloud (VPC) VPC Link Network Load Balancer Service v1.0.0 → v1.0.1 ECS Fargate ※説明の簡単化のために、サブネットや冗長化などは一部簡略化して表記しています。 Internet (HTTPS) インターフェース変更が無くても アプリ内部の振る舞いが変わることを Client が分かるようにバージョンをアップデートする （あえて、サイレントアップデートという手法をとることも・・・） API Gateway のインターフェース変更はないため、 リソース間の依存関係、リリース順を意識せず、デプロイを行うことができる

DEVELOP EFFECTIVE API © 2024, Amazon Web Services, Inc. or its affiliates. All rights reserved. ECS サービスのデプロイと Infrastructure as Code の相性を考える 48

DEVELOP EFFECTIVE API © 2024, Amazon Web Services, Inc. or its affiliates. All rights reserved. IaC のコードと、実リソースの整合性が取れないケース 49 Template AWS CloudFormation AWS CodeDeploy Amazon ECS CodeDeploy や CodePipeline の Deploy フェーズ経由でデプロイをすると、 タスク定義・サービスの設定を CodeDeploy が更新してしまう。 IaC で宣言的に記述している状態と、稼働しているサービスの状態に乖離が発生する。 インフラ管理とアプリ管理用のソースコードが分かれている場合に陥りがちな課題 ローリングアップデート Blue/Green デプロイなど Container Image ECS Service の構築 など v1.0.0 v1.0.1 v1.0.2 v1.0.0 v1.0.0 Infrastructure as Code で定義したリソースと アプリケーションデプロイのライフサイクルが異なる v1.0.0 v1.0.1 v1.0.2

DEVELOP EFFECTIVE API © 2024, Amazon Web Services, Inc. or its affiliates. All rights reserved. IaC のコードと、実リソースの整合性が取れないケース 50 Template AWS CloudFormation AWS CodeDeploy Amazon ECS CodeDeploy や CodePipeline の Deploy フェーズ経由でデプロイをすると、 タスク定義・サービスの設定を CodeDeploy が更新してしまう。 IaC で宣言的に記述している状態と、稼働しているサービスの状態に乖離が発生する。 インフラ管理とアプリ管理用のソースコードが分かれている場合に陥りがちな課題 ローリングアップデート Blue/Green デプロイなど Container Image ECS Service の構築 など v1.0.0 v1.0.1 v1.0.2 v1.0.0 v1.0.0 デプロイの単位と、その境界線をどう設計するか v1.0.0 v1.0.1 v1.0.2 デプロイの最小単位

DEVELOP EFFECTIVE API © 2024, Amazon Web Services, Inc. or its affiliates. All rights reserved. 対策１）全てを AWS CDK で管理する場合 51 Template AWS CloudFormation Amazon ECS すべてを AWS CDK で管理し、CDK の Docker Image Assets などを使用して コンテナのビルドデプロイも CDK のライフサイクルに含めてしまえば整合性はとれる、が ECS Service の構築 など v1.0.0 v1.0.0 CDK でビルド・デプロイ デプロイの最小単位 AWS CDK • アプリ（コンテナ）チームと インフラ（IaC テンプレートを管理する）チームが 分かれている場合に管理しずらい • CDK の Docker Image Assets の仕様に依存する 例）CDK によるデプロイはローリングアップデートのみ 例）一時的に PUSH される ECR ができてしまう v1.0.0 全てを CDK で管理することの弊害

DEVELOP EFFECTIVE API © 2024, Amazon Web Services, Inc. or its affiliates. All rights reserved. 対策２）インフラ・アプリデプロイの境界線を分ける場合 52 A）ECS Service 単位でチームの責務を分離する AWS Account VPC Subnet ECS Cluster ECS Service A Task Task ECS Service B Task Task ECR ECR Service B Application Dockerfile, CloudFormation Spring Boot など Infra Repository AWS CDK AWS CloudFormation など Service A Application Dockerfile, CDK Ruby on Rails など Service A 開発チーム Service B 開発チーム インフラ チーム ownership ownership ownership deploy deploy deploy

DEVELOP EFFECTIVE API © 2024, Amazon Web Services, Inc. or its affiliates. All rights reserved. 対策２）インフラ・アプリデプロイの境界線を分ける場合 53 A）ECS Service 単位でチームの責務を分離する ・IaC で全リソースを１つのコードベースで管理することを諦める ・チームごとに個別にデリバリが可能にする ・チームごとに ECS Service 単位で IaC 管理しても良い ツール選定の Ownership もチームごとに持たせる ・CodeDeploy を採用すれば Blue/Green デプロイも可能に

DEVELOP EFFECTIVE API © 2024, Amazon Web Services, Inc. or its affiliates. All rights reserved. 対策２）インフラ・アプリデプロイの境界線を分ける場合 54 B）コンテナイメージ単位でチームの責務を分離する AWS Account VPC Subnet ECS Cluster ECS Service A Task Task ECS Service B Task Task ECR ECR Infra Repository AWS CDK AWS CloudFormation など Service A Application Dockerfile Ruby on Rails など Service A 開発チーム インフラ チーム ownership ownership deploy push

DEVELOP EFFECTIVE API © 2024, Amazon Web Services, Inc. or its affiliates. All rights reserved. 対策２）インフラ・アプリデプロイの境界線を分ける場合 55 B）コンテナイメージ単位でチームの責務を分離する AWS Account VPC Subnet ECS Cluster ECS Service A Task Task ECS Service B Task Task ECR ECR Infra Repository AWS CDK AWS CloudFormation など Service A Application Dockerfile Ruby on Rails など Service A 開発チーム インフラ チーム ownership ownership deploy push コンテナイメージをビルド、 PUSHするまでを責務とする ❶ インフラチームにリリース対象の コンテナイメージのリビジョンを連携する ❷ リリース対象のコンテナイメージの リビジョンを指定してデプロイ ❸

DEVELOP EFFECTIVE API © 2024, Amazon Web Services, Inc. or its affiliates. All rights reserved. 対策２）インフラ・アプリデプロイの境界線を分ける場合 56 B）コンテナイメージ単位でチームの責務を分離する ・IaC で全リソースを１つのコードベースで管理することを目指す ・チームごとに個別にデリバリはできない（インフラチームが管理） ・チームごとにコンテナを PUSH するまでの フローにOwnership を持たせる ・CodeDeploy を採用すれば Blue/Green デプロイも可能に

DEVELOP EFFECTIVE API © 2024, Amazon Web Services, Inc. or its affiliates. All rights reserved. ECS サービスのデプロイ＋ API Gateway と Infrastructure as Code の相性を考える 57

DEVELOP EFFECTIVE API © 2024, Amazon Web Services, Inc. or its affiliates. All rights reserved. NLB – ECS Service が１つであれば管理は容易だが・・・ 58 開発が進むにつれ、マイクロサービスが増えることは一般的に Amazon API Gateway v1.0.0 Client NLB ECS Fargate Internet (HTTPS) Virtual private cloud (VPC) ※ VPC Link など一部簡略化して表現しています NLB ECS Fargate NLB ECS Fargate

DEVELOP EFFECTIVE API © 2024, Amazon Web Services, Inc. or its affiliates. All rights reserved. デプロイの粒度について考える 59 API Gateway 配下のリソースと IaC の切れ目を考える Amazon API Gateway v1.2.9 Client NLB v1.2.3 Internet (HTTPS) Virtual private cloud (VPC) NLB v1.1.1 NLB v1.0.0 デプロイの単位と、その境界線をどう設計するか デプロイの最小単位

DEVELOP EFFECTIVE API © 2024, Amazon Web Services, Inc. or its affiliates. All rights reserved. OpenAPI でプライベート統合を使用して API を設定する 60 swagger: "2.0" info: version: "2017-11-17T04:40:23Z" ~ 略 ~ paths: "/": get: produces: - application/json responses: "200": description: 200 response schema: "$ref": "#/definitions/XXX" x-amazon-apigateway-integration: responses: default: statusCode: "200" uri: http://my-vpclink-test-nlb-1234567890abcdef.us-east-2.amazonaws.com connectionType: VPC_LINK connectionId: "${stageVariables.vpcLinkId}" passthroughBehavior: when_no_match httpMethod: GET type: http_proxy connectionType, connectionId を明示的に VPC_LINK であることを示す必要がある NLB の uri を指定する

DEVELOP EFFECTIVE API © 2024, Amazon Web Services, Inc. or its affiliates. All rights reserved. API Gateway は誰が管理する？ VPC Subnet ECS Cluster API Gateway Infra Repository deploy Service A Application deploy インフラ管理用のリポジトリで API Gateway も管理するべき？ ECS Service A Task Task ECS Service B Task Task ECR ECR NLB NLB

DEVELOP EFFECTIVE API © 2024, Amazon Web Services, Inc. or its affiliates. All rights reserved. API Gateway は誰が管理する？ VPC Subnet ECS Cluster ECS Service A Task Task ECS Service B Task Task ECR ECR API Gateway Infra Repository deploy Service A Application deploy リソースの依存関係、デプロイの順序は下から上 であればリポジトリを分けてライフサイクルを分けた方が都合が良い ネットワーク系 リソースのデプロイ ❶ API Gateway 層の デプロイ ❸ アプリケーション層の デプロイ ❷ deploy API Repository NLB NLB

DEVELOP EFFECTIVE API © 2024, Amazon Web Services, Inc. or its affiliates. All rights reserved. API Gateway は誰が管理する？ VPC Subnet ECS Cluster API Gateway Infra Repository deploy Service A Application deploy リソースのライフサイクルの切れ目でリポジトリを分けていく チームはリポジトリと１対１で分けても良いし、１対多にしても良い ネットワーク系 リソースのデプロイ ❶ API Gateway 層の デプロイ ❸ アプリケーション層の デプロイ ❷ deploy API Repository インフラ チーム ownership Service A 開発チーム ownership リポジトリさえ分割しておけば 管理主体のチームは分けても分けなくても良い ECS Service A Task Task ECS Service B Task Task ECR ECR NLB NLB

DEVELOP EFFECTIVE API © 2024, Amazon Web Services, Inc. or its affiliates. All rights reserved. ここまでのまとめ 64 • ソフトウェアのライフサイクルごとに リリースのパイプラインを分けていく • パイプラインはブランチを分けて管理しても良いが、 リポジトリごと分けてしまった方が管理が煩雑にならないことが多い • リポジトリを分けておけば、 管理主体のチームが誰であるかは重要ではない。 １つのチームが複数リポジトリを管理しても良い。

DEVELOP EFFECTIVE API © 2024, Amazon Web Services, Inc. or its affiliates. All rights reserved. © 2024, Amazon Web Services, Inc. or its affiliates. All rights reserved. モデルケース３ API Gateway + 様々なマイクロサービス 65 API Gateway 配下のダウンストリームには ECS Fargate, AWS Lambda など様々なサービスが連なる場合も、どう管理していくか

DEVELOP EFFECTIVE API © 2024, Amazon Web Services, Inc. or its affiliates. All rights reserved. 開発と共に増え続けるダウンストリームのリソース 66 例）VPC 外のリソースも登場してきた Amazon API Gateway v1.0.0 Client Network Load Balancer ECS Fargate Internet (HTTPS) Virtual private cloud (VPC) AWS Lambda Amazon DynamoDB AWS Step Functions ※ VPC Link など一部簡略化して表現しています AWS Lambda Amazon SQS

DEVELOP EFFECTIVE API © 2024, Amazon Web Services, Inc. or its affiliates. All rights reserved. デプロイの最小単位、どう決める？ 67 VPC Subnet ECS Cluster API Gateway ECS Service A Task Task ECS Service B Task Task ECR ECR NLB NLB Step Functions Lambda Web用 Lambda Step Functions 用 Dynamo DB ？ ？ ？ ？

DEVELOP EFFECTIVE API © 2024, Amazon Web Services, Inc. or its affiliates. All rights reserved. 課題感 68 • インフラ／アプリという分け方がいよいよ辛くなってきた • StepFunctions や SQS はインフラなのか？ ※ VPC Link など一部簡略化して表現しています

DEVELOP EFFECTIVE API © 2024, Amazon Web Services, Inc. or its affiliates. All rights reserved. 分け方の戦略 69 • 技術カットではなく、ドメインカットでリソース管理を検討する • ソフトウェアのライフサイクルに合わせた リリースの最小単位は依然として守っていく • そして、開発組織も変えていく

DEVELOP EFFECTIVE API © 2024, Amazon Web Services, Inc. or its affiliates. All rights reserved. 技術ではなく、ドメインでチームを分割する 70 Amazon API Gateway v1.0.0 Client Network Load Balancer ECS Fargate Internet (HTTPS) Virtual private cloud (VPC) AWS Lambda Amazon DynamoDB AWS Step Functions ※ VPC Link など一部簡略化して表現しています AWS Lambda Amazon SQS 決済サービス ユーザーサービス ユーザ サービス チーム 決済 サービス チーム インフラ／アプリというチームではなく サービスチームがインフラからアプリまで Ownershipを持つモデルに昇華させる

DEVELOP EFFECTIVE API © 2024, Amazon Web Services, Inc. or its affiliates. All rights reserved. ドメインで分割されたサービスは複数パイプラインが存在 71 AWS Lambda Amazon DynamoDB AWS Step Functions AWS Lambda Amazon SQS 決済サービス Repository A deploy Repository B deploy 例）決済サービスの場合、決済管理・他システム連携など 複数の異なるデリバリのライフサイクルとなるソフトウェア・機能が存在する 決済管理 他システム連携

DEVELOP EFFECTIVE API © 2024, Amazon Web Services, Inc. or its affiliates. All rights reserved. さらに開発規模が大きくなったら？ 72 ドメインごとに API で分割を進める、API単位で Ownership を取れる組織を 決済サービス API v1.0.0 Network Load Balancer ECS Fargate Virtual private cloud (VPC) AWS Lambda Amazon DynamoDB AWS Step Functions AWS Lambda Amazon SQS 決済サービス 注文 サービス チーム 決済 サービス チーム 注文サービス API v1.1.2 AWS Lambda Amazon DynamoDB API Gateway 注文サービス サービスチームの中で さらにマイクロチームを作っても可 マイクロサービスのドメインを集約して 外部に公開 or Front-end に公開するなど デリバリの Ownership を マイクロチームごとに持たせる 全体のデリバリを 管理する人が必要に （Product Owner） Client

DEVELOP EFFECTIVE API © 2024, Amazon Web Services, Inc. or its affiliates. All rights reserved. 外部に API をどう使ってもらうか、 内部で API をどう管理するか 73 API Gateway Client サービスA API サービスB API サービスC API サービスD API Client Client Product Owner サービスA サービスB サービスC サービスD マイクロチームは 開発から運用まで担当する • 設計 • 技術選定 • 採用 • 開発 • テスト（CI） • リリース（CD） • オンコール対応 • 利用者からの問い合わせ etc.. プロダクト全体の意思決定を担当する • ユーザへの価値を最大化するために どんな機能を、いつ、どのボリュームで提供するか決定する • One way door / Two way door の判断 • etc.. 顧客価値の 最大化 開発チーム との調整

DEVELOP EFFECTIVE API © 2024, Amazon Web Services, Inc. or its affiliates. All rights reserved. © 2024, Amazon Web Services, Inc. or its affiliates. All rights reserved. API で会話する組織 74

DEVELOP EFFECTIVE API © 2024, Amazon Web Services, Inc. or its affiliates. All rights reserved. 内部で API をどう管理するか（Product Owner目線） 75 各チームの技術は知る必要がない。 API の仕様と、プロダクトバックログで会話できるようにしていく。 開発チームは API の公開と同時に、 APIドキュメントも最新化する。 API ドキュメントもシステムの一部であると考える。 常に Web UI として公開されている状態を目指す。

DEVELOP EFFECTIVE API © 2024, Amazon Web Services, Inc. or its affiliates. All rights reserved. Redoc や Swagger UI などのドキュメント生成ツール 76 OpenAPI の定義ファイルから API ドキュメントを自動生成する

DEVELOP EFFECTIVE API © 2024, Amazon Web Services, Inc. or its affiliates. All rights reserved. API ドキュメント の公開フロー 77 決済サービス Repository Amazon API Gateway v1.0.0 Amazon CloudFront Amazon S3 HTML CSS, JS AWS Lambda API ドキュメントの アップロード API の公開 Client 開発者や ProcductOwner JSON Webサイトとして公開された API ドキュメント API のリリースと同時に、API ドキュメントも自動生成して更新する AWS CDK AWS CloudFormation AWS SAM Open API Spec など

DEVELOP EFFECTIVE API © 2024, Amazon Web Services, Inc. or its affiliates. All rights reserved. まとめ 78 • 開発組織の規模に応じてアーキテクチャを進化させていく • リリースのパイプラインは、リソースの依存関係に留意して、 チーム体制ではなくリソースのライフサイクルに着目して分ける • 技術カットではなくドメインカットで責務を分けていく • サービスチームごとに意思決定可能なアーキテクチャを目指す ※ VPC Link など一部簡略化して表現しています

DEVELOP EFFECTIVE API © 2024, Amazon Web Services, Inc. or its affiliates. All rights reserved. © 2024, Amazon Web Services, Inc. or its affiliates. All rights reserved. Thank you!

DEVELOP EFFECTIVE API © 2024, Amazon Web Services, Inc. or its affiliates. All rights reserved. © 2024, Amazon Web Services, Inc. or its affiliates. All rights reserved. Thank you!