---
title: '19 AWS API Gateway'
disqus: hackmd
---

:::info
AWS Certified Developer Associate DVA-C01
:::

19 AWS API Gateway
===

<style>
img{
/* border: 2px solid red; */
margin-left: auto;
margin-right: auto;
width: 90%;
display: block;
}
</style>

## Table of Contents

[TOC]

AWS API Gateway
---
- api gateway provides restapi endpts for clients to talk to and invoke lambda functions
- aws lambda + api gateway = no infrastructure to manage
- support for websocket protocol
- can do real time streaming through the api gateway in 2 diff ways
- handle api versioning
- v1, v2 etc.
- handle diff environments
- dev, test, prod
- handle security
- auth and authoristion
- create api keys and handle request throttling
- swagger/open api import/export to quickly define apis
- transform and validate requests and responses
- to ensure invocations are correct
- generate sdk and api specifications
- cache api responses

### Integrations High Level
- lambda func
- invoke lambda func
- easy way to expose rest api backed by aws lambda
- http
- expose http endpts in backend
- eg. internal http api on premise, alb...
- why? add rate limiting, caching, user auth, api keys etc.
- useful to have layer of api gateway on top of http endpt
- aws service
- can expose any aws api through api gateway
- eg. start aws step func workflow, post msg to sqs
- why? add auth, deploy publicly, rate control etc.

### Endpoint Types
- edge-optimised (default)
- for global clients
- requests routed through cloudfront edge locations
- improve latency
- api gateway still lives in only 1 region but accessible from every cloudfront edge location
- regional
- for clients within same region
- could manually combine with cloudfront
- similar to edge optimise more control over caching strategies and distribution
- private
- can only be accessed from vpc using interface vpc endpt (ENI)
- use res policy to define access

### Deployment Stages
- making changes in api gateway dont mean they're effective
- need to make deployment for them to be in effect
- changes are deployed to stages
- can have as many as u want
- use naming you like for stages
- eg. dev, test, prod
- ea stage has own config params
- stages can be rolled back as histoy of deployments is kept
- eg. stages v1 and v2
- v1 clients accessing v1 stage api gateway and v1 lambda func
- v2 api gateway will have new url
- clients can just change url and use new ver
- slowly migrate to v2

#### Stage Variables
- stage vars are like env vars for api gateway
- use to change often changing config values w/o redeploying api
- can be used in
- lambda func arn
- http endpoint
- param mapping templates
- use cases
- config http endpts your stages talk to
- dev, test, prod
- pass config params to lambda through mapping templates
- stage vars passed to context obj in lambda
- can get stage vars directly from func

__API Gateway Stage Vars and Lambda Aliases__
- can create stage var to indicate corresponding lambda alias
- api gateway automatically invoke right lambda func


### Canary Deployment
- possibility to enable canary deployments for any stage
- usually prod
- choose % of traffic the canary channel receives
- metrics and logs are separate
- for better monitoring
- possibility to override stage vars for canary
- is blue/green deployment with aws lambda and api gateway

- % of clients visit the canary stage

### Integration Types
- integration type `MOCK`
- api gateway returns resp w/o sending req to backend
- integration type `HTTP/AWS` (lambda and aws services)
- api gateway forwards a req but we can modify it
- must config both integration req and integration resp
- setup data mapping using __mapping templates__ for req and resp


- integration type `AWS_PROXY` (lambda proxy)
- incoming req from client is input to lambda
- cannot modify req/resp as we're a proxy
- func is responsible for logic of req/resp
- no mapping template
- cannot change headers, query string params etc.
- they are passed as args to funcs directly
- eg. below
- req from api gateway passed like json on the left
- lambda func responsible to take this req, process it and return resp like on the right
- all the work is on the backend and api gateway is just here to proxy the request through


- integration type `HTTP_PROXY`
- no mapping template cuz proxy
- http req is passed to backend
- http resp from backend is forwarded by api gateway


#### Mapping Templates (AWS & HTTP Integration)
- mapping templates can be used to modify req/resp
- rename/modify query string params
- modify body content
- add headers
- use velocity template lang (VTL)
- for loops, if etc.
- is scripting lang to modify requests
- filter output results
- remove unnecessary data

#### Mapping Example
- eg. json to xml with SOAP
- soap api are xml based whereas rest api are json based
- hence, api gateway should
- extract data from req
- either path, payload or header
- build SOAP msg based on req data (mapping template)
- call SOAP service and receive xml response
- transform xml resp to desired format (like json) and respond to user
- api gateway thanks to mapping template can transform json payload into an xml payload


- eg. query string params
- map json vals passed by client into sth lambda can make sense of


### API Gateway Swagger/Open API Spec
- common way of defining rest apis is using api definition as code
- import existing swagger/openapi 3.0 spec to api gateway
- method
- method req
- integration request
- method resp
- + aws extensions for api gateway and setup every single action
- can export current api as swagger/openapi spec
- can be written in yaml/json
- using this we can generate sdk for our apps

### Caching
#### Caching API Responses
- caching reduces num of calls made to backend
- default ttl is 300 seconds
- min 0 seconds, max 3600 seconds
- caches are defined per stage
- possible to override cache settings per method
- cache encryption option
- cache capacity between 0.5gb to 237gb
- cache is expensive
- makes sense in prod but not in dev/test


#### Cache Invalidation
- able to flush/invalidate entire cache immediately
- clients can invalidate cache with `header: Cache-Control: max-age=0`
- needs proper iam perms
- if u dont impose an `InvalidateCache` policy or choose the require authorisation checkbox in console, any client can invalidate the api cache


### Usage Plans and API Keys
- if u want to make an api avail as an offering to your customers
- usage plan
- who can access 1 or more deployed api stages and methods
- how much and how fast they can access them
- use api keys to identify api clients and meter access
- config throttling limits and quota limits that are enforced on indiv client
- api keys
- alphanumeric string vals to distribute to your customers to securely use your api gateway
- eg. WBjHxNtoAb4WPKBC7cGm64CBibIb24b4jt8jJHo9
- can use usage plans to control access
- throttling limits applied to api keys
- quota limits is overall num of max requests

#### Correct Order for API Keys
- to config usage plan
- create 1 or more apis, config methods to require api key and deploy the api to stages
- generate/import api keys to distribute to app devs (customers) who are using your api
- create usage plan with desired throttle and quota limits
- associate api stages and keys with usage plan
- callers of api must supply an assigned key in `x-api-key` header in requests to api

### Logging and Tracing
- cloudwatch logs
- enable cloudwatch logging at stage lvl
- with log lvl
- can override settings on a per API basis
- eg.ERROR, DEBUG, INFO
- log contains info abt request/response body
- xray
- enable tracing to get extra info abt requests in api gateway
- xray api gateway + aws lambda gives u full pic
- cloudwatch metrics
- metrics are by stage
- possible to enable detailed metrics
- `CacheHitCount` and `CacheMissCount`
- efficiency of cache
- `Count`
- total num of api reqs in a given period
- `IntegrationLatency`
- time between when api gateway relays req to backend and when it receives a resp from the backend
- `Latency`
- time between when api gateway receives req from client and when it returns a resp to client
- the latency includes integration latency and other api gateway overhead
- `4XXError` (client side) and `5XXError` (server side)

### API Gateway Throttling
- account limit
- api gateway throttles reqs at 10,000 rps across all api
- soft limit that can be increased upon req
- in case of throttling => 429 too many reqs
- retriable error
- is client error when they do too many reqs
- can set stage limit and method limits to improve performance
- to ensure ea stage dont use all quotas of reqs if it's under atk
- or can define usage plans to throttle per customer
- just like lambda concurrency, 1 api if overloaded or limited can cause other apis to be throttled

#### Errors
- 4xx means client errors
- 400 - bad request
- 403 - access denied, waf filtered (firewall dont accept your request)
- 429 - quota exceeded, throttle
- 5xx means server errors
- 502
- bad gateway exception
- usually for incompatible output returned from a lambda proxy integration backend and occasionally for out-of-order invocations due to heavy loads
- 503
- service unavailable exception
- 504
- integration failure
- eg. endpt request timeout exception
- api gateway requests timeout after 29 seconds maximum

### CORS
- cors must be enabled when u receive api calls from another domain
- OPTIONS pre-flight req must contain following headers
- `Access-Control-Allow-Methods`
- `Access-Control-Allow-Headers`
- `Access-Control-Allow-Origin`
- cors can be enabled through the console

- browser goes to s3 to get static content
- js in content from s3 bucket makes api calls to cross origin
- hence browser as security will make OPTIONS pre-flight req to api gateway
- api gateway gives us preflight resp if the origin is allowed to make a cross origin request
- if everything is well, browser and gateway can talk to one another

### API Gateway Security
#### IAM Permissions
- create iam policy authorisation and attach to user/role
- iam - auth
- iam policy - authorisation
- good to provide access within aws
- eg. ec2, lambda, iam users
- leverages sigv4 capability whr iam credentials are signed and placed in headers

- client first do restapi call and pass sigv4 headers to api gateway
- api gateway decrypts those and check with iam if the user is authorised (iam policy check)
- if done, apigateway is authorised and talks to lambda in backend

#### Resource Policies
- res policies
- similar to lambda res policy
- allow u to set adj policy on api gateway to define who and what can access it
- allow for cross acc access (is main use case) combined with iam security
- allow for specific src ip addr
- allow for vpc endpt


#### Cognito User Pools
- cognito fully manages user lifecycle
- token expires automatically
- api gateway verifies identity automatically from aws cognito
- no custom implementation required
- auth - cognito user pools
- authorisation - api gateway methods

- client first auths with cognito user pools to retrieve a conn token
- passes token in api call to our api gateway
- api gateway with direct integration with cognito user pools will evaluate the token with user pool
- if token correct, allow access to your backend

#### Lambda Authoriser (formerly Custom Authorisers)
- token-based authoriser (bearer token)
- eg. jwt or oauth
- request param based lambda authoriser
- passed with headers, query string, stage var
- lambda must return an iam policy for the user
- result policy is cached
- auth - external
- authorisation - lambda func

- client auths with 3rd party auth system eg. auth0
- get token from 3rd party and pass to api gateway
- either through header or request biometrics
- api gateway integrated with lambda authoriser (which is a lambda func)
- authoriser retrieve info around the context and token
- the func is up to us to code so we'll decide how it communicates with the 3rd party to verify the token
- if token valid, authoriser creates an iam principal and iam policy
- policy cached inside a policy cache

#### Security Summary
- iam
- great for users/roles alr within aws acc
- and res policy for cross acc
- handle auth and authorisation
- leverages sigv4
- custom authoriser
- great for 3rd party tokens
- very flexible in terms of what iam policy is returned
- handle auth verification and authorisation in lambda func
- pay per lambda invocation
- results cached
- cognito user pools
- manage own user pool
- can be backed by facebook, google login etc.
- no need write any custom code
- must implement authorisation in backend

### HTTP vs REST vs Websocket API
- http apis
- low latency
- cost effective aws lambda proxy, http proxy apis and private integration
- no data mapping (all proxies)
- support OIDC and OAuth 2.0 authorisation
- built-in support for cors
- no usage plans and api keys
- is low cost alternative and only support proxy integration
- rest apis
- all features except native OpenID Connect/OAuth 2.0
- https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-vs-rest.html


- websocket api
- is 2 way interactive communication between a user's browser and a server
- server can push info to client
- this enables stateful app use cases
- websocket apis are often used in realtime apps like chat apps, collab platforms, multiplayer games and financial trading platforms
- works with aws services (lambda, dynamodb) or http endpts

### Console
- http api
- works with lambda or http backends
- websocket api
- works with lambda, http and aws services
- rest api
- and also restapi private for within vpc

- rest api example
- choos endpt type
- regional
- deployed within this region
- edge optimised
- using cloudfront edge network
- private
- within vpc

- use actions to create method

- choose integration type
- aws service can expose any service in any region
- vpc link
- when we have vpc inside of vbc (out of scope for this exam)
- lambda proxy integration
- also have to create lambda func for this endpt
- set timeout
- lambda func has timeout of up to 15mins, but this default is 29 seconds max
- can set custom timeout

- lambda res policy allows api gateway

- there's method, integration request


- can click on endpt and test it
- see resp body, headers and logs

- example request sent to lambda from api gateway seen in cloudwatch logs

- can create resource

- choose http verb to use for endpt

- to deploy api, go to actions

- indicate stage name eg. dev

- invoke url created for your use

#### Stages
- create lambda alias

- create method for your endpt

- paste your lambda func name into your method
- but append to name `:${stageVariables.lambdaAlias}`

- need to use cli to add res based policy for each func version/alias to allow api gateway to invoke the corresponding func
- replace function name param's last section after the `:` with the aliases of the function
- currently the console doesnt do this for us

- test endpt with your stage variable

- deploy api

- can go into your deployed api and set your stage variable depending on which deployment stage it's in

#### Stage Options
- for ea stage can config
- cache settings
- method throttling
- so not called too often
- webapp firewall settings
- client certs
- for ssl login

- logs and tracing
- cloudwatch logs
- details metrics
- access logging
- xray tracing

- generate code based on what u want (lang)

- export api as either swagger or open api 3

- deployment history which shows all deployments

- for stage documentation

- canary

#### Canary
- create canary in canary tab of your deployment stage
- edit % directed to canary and prod

- can deploy api to only canary of a stage
- clients directed based on %

#### Mapping Templates
- click on integration response > mapping template > json

- return `renamedExample` with val of `inputRoot.example` which is var in the lambda func
- can change response however we want

#### Import/Export Swagger/OpenAPI
- when creating gateway, can choose to import as rest api

- example api that describes your api

- can go to sdk generation tab of gateway to generate an sdk depending on lang

- export api
- can choose json or yaml


#### Caching
- go to console settings and click enable api cache
- caching is not in free tier


- stop at 118gb but max is still 237gb

#### Usage Plans
![Uploading file..._a6i3s412p]()
- in method execution of method, can set api key required field to true

- go to usage plan tab on sidebar


- config throttling
- how many reqs per second i want to get max
- burst
- how much i allow my customers to go over
- quota
- eg. cannot do more than 10,000 requests per month
- can change month to week or day


- click add api stage to associate a stage


- next create api keys

- usage plan created

- can see usage of a specific customer
- click on usage under api key tyab

- can grant an extension of reqs to specific api key


- api key panel


- can enable method throttling to specific method of gateway through your usage plan console

- can sell api key directly on aws marketplace

- will see message forbidden if your api key is not passed in the headers

- get status 200 if key passed

#### CORS
- js in static content fetch sth from your api gateway url


- go actions > enable cors for specific method u want

- if leave access control allow origin to \*, it'll work for every website
- can just change to the domain you'll be calling the fetch from
- also need to redeploy api for it to work

- enabling cors might not work if your method is a proxy
- can be seen from integration response window

- OR u can just manually add the header in your lambda func

#### Security
- under method execution can set authorisation
- currently only has iam

- use tgt with res policy
- has 3 examples
- aws acc whitelist
- cross acc res policy
- can replace with another acc id

- ip range blacklist

- src vpc whitelist
- authorise another vpc into our gateway

- go to authorisers on sidebar to create new authorisers


Quiz
---
- i thought latency was a part of cloudwatch metrics instead of xray but ok

###### tags: `AWS Developer Associate` `Notes`