CULTURE

AWS SAMデプロイ時のAPIリソースパス設計における注意点 - 同一パスで異なる変数名を使用する際の制約

2025.03.03

プロダクト

目次[]

はじめに
問題のシナリオ
なぜエラーが発生するのか？
API Gatewayのリソース構造
具体的な制約
正しい設計アプローチ
1. 統一された変数名の使用
参考ドキュメント
トラブルシューティング
よくあるエラーパターン
解決のアプローチ
まとめ
補足情報
API Gateway v2 (HTTP API) での違い
CICDパイプラインでの注意点

はじめに

Uniforceでバックエンドを担当している鈴木です。

AWS Serverless Application Model (SAM) を使用してAPIをデプロイする際、API Gateway のリソースパス設計において思わぬ制約に遭遇することがあります。本記事では、特に同一パスパターンで異なるHTTPメソッドを定義する際の注意点について、実例を交えて解説します。

問題のシナリオ

以下のような2つのlambdaを定義しようとした際に発生した問題について説明します：

# 間違った template.yaml の例
Resources:
  EditTask:
    Type: AWS::Serverless::Function
    Properties:
      Path:
        /task/{**task_id**}
      Method: put
  DeleteTask:
    Type: AWS::Serverless::Function
    Properties:
      Path:
        /task/{**task_number**}
      Method: delete

このような定義を行った場合、SAMデプロイ時にCloudFormationのエラーが発生します。

なぜエラーが発生するのか？

API Gatewayのリソース構造

API Gatewayでは、APIリソースは以下のような階層構造で管理されています：

リソースパス（/task/{param}）
HTTPメソッド（GET, POST, PUT, DELETE等）

重要なポイントは、パスパラメータの変数名がリソースの識別子として扱われるということです。つまり、同じパスパターンで異なる変数名を使用することはできません。

具体的な制約

同一パスパターン（例：/task/{param}）において、異なるHTTPメソッド間でパスパラメータの変数名を変えることはできない

正しい設計アプローチ

1. 統一された変数名の使用

# 正しい例
Resources:
  EditTask:
    Type: AWS::Serverless::Function
    Properties:
      Path:
        /task/{**task_id**}
      Method: put
  DeleteTask:
    Type: AWS::Serverless::Function
    Properties:
      Path:
        /task/{**task_id**}
      Method: delete

参考ドキュメント

トラブルシューティング

よくあるエラーパターン

CloudFormationスタックの作成エラー

Error: Resource handler returned message: "Unable to put method (Service: AmazonApiGateway...)

このようなエラーが発生した場合、以下を確認します：

パスパラメータの命名の一貫性
リソースパスの重複
メソッド定義の競合

解決のアプローチ

SAMテンプレートの検証

sam validate

APIリソース構造の確認

aws apigateway get-resources --rest-api-id <api-id>

CloudFormationスタックのイベント確認

aws cloudformation describe-stack-events --stack-name <stack-name>

まとめ

AWS SAMを使用したAPIのデプロイでは、API Gatewayのリソース構造を理解し、適切なパス設計を行うことが重要です。特に：

同一パスパターンでは、異なるHTTPメソッド間でも変数名を統一する
異なる意味を持つパラメータは、パスパターン自体を変える
API全体で一貫性のある命名規則を採用する

これらの原則に従うことで、デプロイの問題を回避し、保守性の高いAPIを設計することができます。

補足情報

API Gateway v2 (HTTP API) での違い

API Gateway v2（HTTP API）では、より柔軟なパス設計が可能ですが、基本的な設計原則は同じです：

CICDパイプラインでの注意点

AWS SAMを使用したCICDパイプラインを構築する際は、以下の点に注意が必要です：

テンプレートの検証ステップの組み込み
スタック更新の依存関係の管理
ステージごとの環境変数の管理

詳細はAWS SAM CICDガイドを参照してください。

Writer

Uniforce株式会社　バックエンドエンジニア

鈴木