[AWS] API Gateway

API Gateway is a fully managed API endpoint service that creates, manages, publishes, monitors, secures, and scales APIs. API Gateway can use other AWS services (Lambda, DynamoDB) for compute and store.

https://aws.amazon.com/api-gateway/

• API (Application Programming Interface): Applications use APIs to communicate with other applications.
• API Gateway is often used as the front door to a serverless application.

Features

• API Gateway is a service that provides a single endpoint for traffic from all clients interacting with the backend applications running on Lambda or EC2 and services like DynamoDB or Kinesis.

Managing APIs

• API Gateway can act as a front door for existing APIs and can be scaled to meet the demand.
• API Gateway allows you to publish, maintain, secure, and monitor APIs at any scale.

• Pricing is based on the number of API calls, the amount of data transferred, and any caching.
• API Gateway can access some AWS services directly using proxy mode.

• Low Latency and Throttle Control
  • The Lowest possible latency by taking advantage of the Amazon CloudFront global network of edge locations.
  • API Gateway Cache for frequently accessed content
  • DDoS (Distributed Denial of Service) protection via CloudFront
• Flexible Authentication and Authorization Options
  • Amazon Cognito
  • IAM
  • Custom Lambda Authorizer
• Can be used with AWS Certificate Manager (ACM): free SSL/TLS certificates
• The same-origin-policy is important to secure your API from Cross-Site Scripting (XSS) attacks. CORS (Cross Origin Resource Sharing) is the way to loosen the policy.

Developer Features

• Multiple version Support
  • You can run multiple versions of the same API simultaneously so that you can quickly iterate, test, and release new versions.
• Request/Response Data Transformation and Validation
• Monitoring & Debugging
  • You can use AWS X-Ray to trace and analyze user requests as they travel through your Amazon API Gateway APIs to the underlying services.
• Quick SDK Generation
  • API Gateway can generate client Software Development Kits (SDKs) for several platforms and distribute SDKs to third-party developers.

Supported API Types

REST (Representational State Transfer) APIs

API Gateway provides the REST APIs and simplified HTTP APIs.

• General Features
  • Optimized for stateless and serverless workloads such as web applications
  • Supports JSON (JavaScript Object Notation) with key/value pairs
• Endpoints
  • Regional endpoint
    • provides lower latency for applications that invoke your API within the same Region
  • Edge-optimized endpoint
    • works with a fully managed CloudFront distribution
  • Private endpoint
    • routes requests only within a single VPC using an Interface VPC endpoint
    • A resource policy is used to control access
  • Changing endpoint types
    • from edge-optimized to regional or private: Supported
    • from regional to edge-optimized or private: Supported
    • from private to regional: Supported
    • from private to edge-optimized: NOT SUPPORTED
• Choosing between REST APIs and HTTP APIs – Amazon API Gateway

Websocket APIs

• Used for real-time, two-way, long-lived stateful communications
• WebSocket routes
  • With WebSocket APIs,
    • JSON messages can be routed to invoke a specific backend service based on message content.
    • Non-JSON messages are routed to the $default route.
  • Each route can be set to one-way or two-way communication.
  • There are 3 predefined routes:
    • $connect
      • The client application connects to your WebSocket API by sending a WebSocket upgrade request.
      • If the request succeeds, the $connect route is invoked.
      • The upgrade request is pending until the $connection route is completed.
    • $default
      • After the connection is established,the client message can be routed to the backend service.
    • $disconnect
      • The $disconnect route is invoked after the connection is closed.
      • It is the best-effort event. There is no guaranteed delivery.
  • You can add a custom route.
• WebSocket Selection Expressions
  • A Websocket API uses selection expressions as a way to evaluate the request and response context and produce a key.
  • A specified JSON property is expected to be present in the message payload.

Caching

API Gateway caches the endpoint response to improve the latency for requests.

• This is an optional configuration only available for REST APIs.
• API Gateway Caching is used to cache the endpoint’s response per Stage (a cache key).
  • You can override stage-level settings for individual methods.
• Caching is used to improve the latency of the requests to APIs.
• Only GET methods can be cached.
• API Gateway caches responses for a specified time-to-live (TTL) period in seconds.
  • The default is 300 seconds (5 mins).
  • The maximum is 3,600 seconds (1 hour).
• Caching is in the Stage settings.
• Caching is expensive. Only use it for the production environment.

Invalidating Cache

• Permision

{
  "Effect": "Allow",
  "Action": [ "execute-api:InvalidateCache" ],
  "Resource": [ "arn:..:<api-id>/<stage>/GET/..." ]
}

• Invalidate the cache with the header
  • Cache-Control: max-age=0

Components

• Resource:
  • A logical entity that can be accessed via the resource path (resource URL)
  • When adding a resource, you have the option to create a proxy resource as well. With the proxy, Gateway simply passes the entire request and response between the frontend and the backend.
    1. To use the proxy option, you first configure the resource as a proxy resource
       • Create a proxy resource with a greedy path variable of {proxy+}.
       • Set the ANY method on the proxy resource.
       • Integrate the resource with a backend using the HTTP or Lambda integration type.
    2. And then set up an integration type of either HTTP or Lambda proxy when creating the method.
• Method
  • A method can be associated with a resource and responds to the request (HTTP Verbs such as GET, PUT, …)
  • You can set up the timeout and the integration type.
• Deployment
  • A snapshot of API’s resources and methods
  • must be associated with a stage
• Stage
  • APIs are deployed into stages (different environments: dev, productions);
  • A stage is a snapshot of the API – methods, integration, models, mapping templates, and Lambda authorities. It supports AWS Certificate Manager (ACM).
  • Each stage has its own unique invoke URL.
  • Stage variables can be used to reference a different backend endpoint such as a different Lambda function or a different HTTP endpoint url.
    • $stageVariables.[variable name]
    • Stage variables are passed to the “context” object in Lambda functions
  • You can configure the following settings in a stage level:
    • Caching
    • Throttling
    • Usage Plans
    • Export APIs
  • You can use Stages with canary deployments to test new versions.

URLs

The default URL looks like this:

https://<restapi_id>.execute-api.<region>.amazonaws.com/<stage>/[resource]

• The custom domain name can be used.
• API Gateway is integrated with “AWS Certificate Manager (ACM)” and lets you import your own certificate or generate a Secure Sockets Layer (SSL) certificate with ACM. 
  • For edge-optimized endpoints, the certificate must be in “us-east-1” region
  • For regional endpoints, the certificate should be in the same region with the API
  • must setup CNAME or A-alias record in Route 53

API Authorization

• JWT (JSON Web Token)
  • OpenID Connect (OIDC)
    • A simple identity layer on top of the OAuth 2.0
  • Supports federated identities for web and mobile users
  • HTTP APIs
    • JWT authorizers
  • REST APIs
    • Amazon Cognito User Pools (which use JWT authorizers)
• AWS IAM Permissions
  • Requires IAM credentials
  • Not good for web/mobile apps with a large number of users
    • Maximum 5,000 users
• Lambda Authorizers
  • Custom authorization
    • A Lambda authorizer is an API Gateway feature that uses a Lambda function to control access to the API.
  • Types of Lambda Authorizers
    • Token-based: A bearer token (JWT or OAuth token) as a caller’s identity
    • Request-parameter-based: headers, query parameters, stage variables, or $context variables

API Gateway also supports certificate-based authentication via mutual Transport Layer Security (mTLS).

Authentication/Authorization Process

Authorizing with IAM

1. All requests to APIs are required to be signed using the AWS Version 4 signing process (Sig v4).
   • The key info is added to the Authentication header.
2. IAM User/Role Acquisition
   • IAM uses your AWS access key and the secret key to compute an HMAC (Hash-based Message Authentication Code) signature using SHA256.
3. API Gateway takes the signed request, parse it, and determine whether the signed user has a proper permission to invoke the API.

Authorizing with Lambda Authorizers

1. API Gateway calls the lambda function upon request.
   • Uses a token or request parameters
2. The lambda function returns a policy that allows or denies the request.
3. The policy can be cached (optional) to reduce the number of invocation of the lambda function.

# Input to Lambda Authorizer from API Gateway
# Token-based

{
  "type": "TOKEN",
  "authorizationToken": "...",
  "methodArn": "arn:aws:execute-API:..."
}

# Input to Lambda Authorizer from API Gateway
# Parameter-based

{
  "type": "REQUEST",
  "methodArn": "arn:aws:execute-API:...",  
  "httpMethod": "GET",
  "headers": {
   "name": "value"
  },
  "queryStringParameters": {
    "key": "value" 
  }, 
  "stageVariables": {
    "var1": "value"
  },
  ...
}

# Output: JSON Policy

{
  "policyDocument": {
    "Version": "2012-10-17"
    "Statement": [
      "Action": "execute-api:Invoke",
      "Effect": "Allow|Deny",
      "Resource": "arn:aws:execute-API:..."
    ]  
  }
}

Authorizing with Cognito User Pools

1. A user is authenticated against the user pool.
2. A user acquires the OIDC (OpenID Connect) token formatted in a JWT (JSON Web Token).
3. The token is sent to API in the request header.
4. You can invoke the API only with the valid token.

IAM Policies and Resource Policies

IAM Policies

• An IAM policy is used to grant permission to a user, group, or role.
• There are 2 types of permissions in API Gateway.
  • Who can invoke the API
    • To call an API, the caller needs the execute-api:* permission.
  • Who can manage the API
    • To create, deploy, and manage an API, the API developer needs the apigateway:* permission.

{
  "Version": "2012-10-17"
  "Statement": [
    "Action": "execute-api:Invoke",
    "Effect": "Allow",
    "Resource": "arn:aws:execute-API:us-east-1:..."
  ]  
}

{
  "Version": "2012-10-17"
  "Statement": [
    "Action": "apigateway:GET",
    "Effect": "Allow",
    "Resource": "arn:aws:apigateway:us-east-1:..."
  ]  
}

Resource Policies

• A resource policy is a JSON policy document that you attach to an API.
• It is used to limit access by users from a specified account, IP address range, VPC, or VPC endpoint.
• Also you can give the API permissions to access other services such as a lambda function.

{
  "Version": "2012-10-17"
  "Statement": [
    "Action": "lambda:invokeFunction",
    "Effect": "Allow",
    "Principal": {
      "Service": "apigateway.amazonaws.com"
    },    
    "Resource": "arn:aws:lambda:us-east-1:...",
    "Condition": {
      "ArnLike": {
        "AWS:SourceArn": "arn:aws:execute-API:us-east-1:..."
      }
    }
  ]  
}

API Throttling

API Gateway manages traffic with throttling so that backend applications can withstand traffic spikes and denial of service attacks.

• Throttling rules can be used to set the number of requests per second.
• Limits
  • Default limit: 10,000 requests per second (rps) per region
  • Concurrent limit: 5,000 concurrent requests across all APIs within an account
• Any request over the limit will receive a 429 HTTP response (Too many requests).

Ex) If there are more than 5K requests per second, 5K requests are handled immediately, and API Gateway throttles the rest within the one-second period.

• CloudWatch can be used to monitor API Gateway activity, usage, and throttling rules.
  • Throttling limits can be set for standard rates and burst rates. For example, you can set a standard rate limit of 1,000 requests per second for a specific REST method and also configure a burst rate of 2,000 requests per second for a few seconds.

Integration with Backend

When you create a method, you need to determine how the request passes to backend – integration type -.

Import/Export APIs

• The API Gateway Import feature is used to import an API from the external definition file into API Gateway.
  • Swagger or OpenAPI 3.0

Logging – CloudWatch Logs

There are 2 types of logging in API Gateway; “Access Logs” and “Execution Logs“. By default, logging is NOT configured for a new API.

Monitoring

There are 7 basic CloudWatch metrics for API Gateway.

• General
  • Count: Total number of API requests in a period
• Caching
  • CacheHitCount: Number of requests served from the API cache in a given period
  • CacheMissCount: Number of requests served from the backend in a given period, when API caching is turned on
• Calculating Overhead
  • Latency: How long it takes for a full round-trip response, from the moment a client invokes the API to when the API responds with the results
  • Integration Latency: how long it takes for API Gateway to make the invocation to the backend and receive the response
• Errors
  • 4xxError: Client-side errors captured in a specified period
  • 5xxError: Server-side errors captured in a specified period

Using X-Ray

• Analyze latency and debug errors in your APIs and their backend services.
• Configure sampling rules to focus on specific requests.

Data Mappings & Request Validation

Template Mapping

You can use the Apache Velocity Template Language (VLT) to map inputs or outputs.

• https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-mapping-template-reference.html

Request Validation

• https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-method-request-validation.html
• When the validation fails, API returns a 400-error response
  • This reduces unnecessary calls to the backend.
• Checking:
  • Request Parameters: URI, Query strings, and headers
  • Request Payload: against JSON schema request model

Build & Deployment

• Use API Gateway Stages with Lambda Aliases
  • In Lambda, enable versioning and use aliases to reference.
  • In API Gateway, use stages for environments.
  • Point API Gateway stage variables at the Lambda aliases.
• Use Canary Deployment
  • API Gateway makes a base version and updated versions of the API on the same stage.
  • You can choose % traffic splitting.

API Gateway Usage Plan

API Gateway Usage Plans make your APIs available as product offerings for your customers.

• A usage plan specifies who can access deployed APIs (stages and methods) and also how much and how fast they can access them.

API keys are used to identify API clients.

• An API key has a name and a value.
  • The terms “API key” and “API key value” are often used interchangeably.
  • The value is an alphanumeric string between 20 and 128 characters.
  • The value must be unique.
• Customers include the API key through x-API-key header in requests. 

You can control customers’ API usage by:

• Throttling limit
  • the target point at which request throttling should start
  • ex) 50 requests per second
• Quota limit
  • the target maximum number of requests with a given API key that can be submitted within a specified time interval
  • ex) 10,000 requests per day

Best Practices

• Do not use API keys for authentication or authorization for your APIs.
• Use API keys that API Gateway generates.
• API keys shouldn’t include confidential information.