API deployment and stages in AWS - Commands & Configuration

Introduction

When you create an API on AWS, you need to deploy it so people can use it. Deployment means making your API live. Stages let you have different versions of your API, like testing or production, so you can try changes safely before everyone uses them.

When you want to make your API available on the internet after building it.

When you want to test new API changes without affecting users by using a separate stage.

When you want to have a stable version of your API for customers and a development version for your team.

When you want to organize your API versions clearly for easier management.

When you want to roll back to a previous API version if something goes wrong.

Commands

This command creates a new REST API named MyExampleAPI in AWS API Gateway.

Terminal

aws apigateway create-rest-api --name MyExampleAPI

Expected Output

{

    "id": "a1b2c3d4e5",

    "name": "MyExampleAPI",

    "createdDate": "2024-06-01T12:00:00Z",

    "endpointConfiguration": {

        "types": ["REGIONAL"]

    }

}

→

--name - Sets the name of the new API.

This command deploys the API with ID a1b2c3d4e5 to a stage named 'dev', making it accessible for testing.

Terminal

aws apigateway create-deployment --rest-api-id a1b2c3d4e5 --stage-name dev

Expected Output

{

    "id": "d6f7g8h9i0",

    "createdDate": "2024-06-01T12:05:00Z",

    "stageName": "dev"

}

→

--rest-api-id - Specifies which API to deploy.

→

--stage-name - Names the deployment stage.

This command lists all deployment stages for the API with ID a1b2c3d4e5, so you can see available versions.

Terminal

aws apigateway get-stages --rest-api-id a1b2c3d4e5

Expected Output

{

    "item": [

        {

            "stageName": "dev",

            "deploymentId": "d6f7g8h9i0",

            "createdDate": "2024-06-01T12:05:00Z"

        }

    ]

}

→

--rest-api-id - Specifies which API's stages to list.

This command deploys the API to the 'prod' stage, making it the live version for users.

Terminal

aws apigateway create-deployment --rest-api-id a1b2c3d4e5 --stage-name prod

Expected Output

{

    "id": "j1k2l3m4n5",

    "createdDate": "2024-06-01T12:10:00Z",

    "stageName": "prod"

}

→

--rest-api-id - Specifies which API to deploy.

→

--stage-name - Names the deployment stage.

Key Concept

If you remember nothing else from this pattern, remember: deploying your API to different stages lets you test safely and release updates smoothly.

Common Mistakes

Deploying the API without specifying a stage name.

The deployment will succeed but no stage is created, so the API won't be accessible.

Always use the --stage-name flag to create a stage during deployment.

Using the wrong API ID when deploying or listing stages.

Commands will fail or show no results because the API ID does not match any existing API.

Double-check the API ID from the create-rest-api output before running deployment or stage commands.

Not creating a deployment after making API changes.

Changes won't be visible to users until a new deployment is created.

Run create-deployment with the correct API ID and stage name after any API updates.

Summary

Create a new REST API using aws apigateway create-rest-api.

Deploy the API to a named stage using aws apigateway create-deployment with --stage-name.

Check existing stages with aws apigateway get-stages to manage versions.

Use stages to separate testing and production environments for safe updates.