How to Use Path Parameters in AWS API Gateway

In AWS API Gateway, use {parameterName} in your resource path to define path parameters. These parameters capture dynamic parts of the URL and can be accessed in your backend integration or Lambda function.

Syntax

Path parameters are defined by enclosing the parameter name in curly braces within the resource path. For example, /users/{userId} defines a path parameter named userId.

When a client calls /users/123, the value 123 is captured as the userId parameter.

plaintext

/resource/{parameterName}

Example

This example shows how to create a GET method with a path parameter userId and access it in a Lambda function integration.

yaml

Resources:
  ApiGatewayRestApi:
    Type: AWS::ApiGateway::RestApi
    Properties:
      Name: UserApi

  ApiGatewayResourceUser:
    Type: AWS::ApiGateway::Resource
    Properties:
      ParentId: !GetAtt ApiGatewayRestApi.RootResourceId
      PathPart: users
      RestApiId: !Ref ApiGatewayRestApi

  ApiGatewayResourceUserId:
    Type: AWS::ApiGateway::Resource
    Properties:
      ParentId: !Ref ApiGatewayResourceUser
      PathPart: "{userId}"
      RestApiId: !Ref ApiGatewayRestApi

  ApiGatewayMethodGetUser:
    Type: AWS::ApiGateway::Method
    Properties:
      HttpMethod: GET
      ResourceId: !Ref ApiGatewayResourceUserId
      RestApiId: !Ref ApiGatewayRestApi
      AuthorizationType: NONE
      Integration:
        Type: AWS_PROXY
        IntegrationHttpMethod: POST
        Uri: !Sub arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${UserLambdaFunction.Arn}/invocations

  UserLambdaFunction:
    Type: AWS::Lambda::Function
    Properties:
      Handler: index.handler
      Runtime: nodejs18.x
      Role: arn:aws:iam::123456789012:role/lambda-execution-role
      Code:
        ZipFile: |
          exports.handler = async (event) => {
            const userId = event.pathParameters.userId;
            return {
              statusCode: 200,
              body: JSON.stringify({ message: `User ID is ${userId}` })
            };
          };

Output

{"message":"User ID is 123"}

Common Pitfalls

• Forgetting to enclose the parameter name in curly braces {} in the resource path.
• Not enabling pathParameters in the integration request mapping, so the backend cannot access the parameter.
• Using the wrong parameter name in the Lambda event object; it must match exactly.
• Not deploying the API after changes, so updates are not live.

plaintext

Wrong resource path:
/resource/userId  # Missing curly braces

Correct resource path:
/resource/{userId}

Quick Reference

Use this cheat sheet to remember how to work with path parameters in API Gateway:

Concept	Example	Notes
Define path parameter	/items/{itemId}	Use curly braces around parameter name
Access in Lambda	event.pathParameters.itemId	Parameter name is case-sensitive
Invoke URL	https://api.example.com/items/42	42 is the value of itemId
Deploy API	aws apigateway create-deployment	Required to apply changes
Integration type	AWS_PROXY or HTTP	Supports passing path parameters

Key Takeaways

Define path parameters by enclosing names in curly braces in the resource path.

Access path parameters in Lambda via event.pathParameters with exact parameter names.

Always deploy your API after changes to make path parameters effective.

Ensure integration request passes path parameters to backend correctly.

Test your API with real URLs to verify path parameter capture.