Wilson Mar bio photo

Wilson Mar


Calendar YouTube Github



US (English)   Norsk (Norwegian)   Español (Spanish)   Français (French)   Deutsch (German)   Italiano   Português   Estonian   اَلْعَرَبِيَّةُ (Egypt Arabic)   Napali   中文 (简体) Chinese (Simplified)   日本語 Japanese   한국어 Korean


To see for yourself, go through the 35-minute self-paced lab Introduction to Amazon API Gateway. In the lab, you create a simple FAQ microservice. The microservice returns a JSON object containing a random question and answer pair using an API Gateway endpoint that invokes a Lambda function. So students should take the prerequisite lab “Introduction to AWS Lambda” before taking this lab.

This is an expanded version of that lab. This tutorial takes a deep dive into creating and using AWS API Management. This is a hands-on guided tour. Take one step at a time and we point out PROTIPs and notes along the way.

High level orientation

According to https://aws.amazon.com/api-gateway/details Amazon’s API Gateway “is a fully managed service that makes it easy for developers to create, publish, maintain, monitor, and secure APIs at any scale”.

See my API Management Evaluation page to compare features such as:

  • Deploy an API to multiple stages, allowing easy differential between development, test, production, as well as versioning
  • Connect custom domains to an API

  • Define models to help standardize API request and response transformations
  • Transform the body and headers of incoming and outgoing API requests to match backend systems

  • Control API access via Amazon Identity and Access Management
  • Create and apply API keys for third-party development
  • Enable Amazon CloudWatch integration for API monitoring
  • Cache API responses via Amazon CloudFront for faster response times

API Design

To get started, it helps to have a design mapped out.

Each “resource” is a single microservice within a system, with a URL such as “https://api.mysite.com/questions”.

Each “method” is the combination of a resource path and an HTTP verb such as GET, POST, DELETE, etc. in the HTTP header.

Several “stages” (such as “dev”, “prod”, etc.) can be defined to hold resources and methods, which are usually different for different environments.

Define an API

  1. In the internet browser open a new tab to go to Services > Application Services > API Gateway.

  2. Click on the link to a API microservice you created.

    PROTIP: Pre-define a naming standard so you can locate specific ones when you several pages of them. , such as “LambdaMicroservice” or “PS1-quiz1-v01”.

    PROTIP: From the first version have a version number to avoid the time, confusion, and mistakes from renumbering after creation.

  3. Click on the link to its GET method.

    Marvel at the visualization and blinking icons.

    Test call

  4. Click on the Test link for an explanation of conditions before clicking Test.

  5. Review the response metadata:

    Status: 200
    Latency: 527 ms

    QUESTION: What is the latency that can be expected? Different latencies can be expected for different paths between client and server end-point location.

    QUESTION: Are alerts issued if latency is higher than an expected level?

    QUESTION: How are alerts about latency resolved?

  6. Scroll down the log for Endpoint request headers clients put in the HTTP header coming into Lambda:

    x-amzn-lambda-integration-tag=test-request, Authorization=*...*8e4876, 

    QUESTION: Where is the documentation for those writing requests?

  7. Scroll down the log for Endpoint response headers in the HTTP header back to the client:

    Date=Fri, 03 Jun 2016 18:13:09 GMT, 

    QUESTION: Is there a library for client programmers can use to more quickly get their code to read responses?

    QUESTION: Is there a specification of these interactions in Swagger, RAML, WADL, etc.?

External API Access

  1. Return to Services > Application Services > API Gateway

    aws api svc menu 2016-06-03 182x205

  2. Click Stages under the microservice name.

  3. Click the URL in blue, such as:


    TROUBLESHOOTING: If message “Missing Authentication Token” appears, make sure Security is set to Open.

    QUESTION: Is the response in HATEOAS (Hypermedia), with permissible next requests?

    aws api left menu 2016-06-03

    Test API methods

  4. Click the tiny arrow to the left of a stage (such as prod or dev) to expand the tree.

  5. Click a command defined, such as GET.

  6. Click the URL in blue, such as:


  7. Add other methods according to the design.

More on API Microservices

This is one of a series: