Designing APIs on AWS

Developing applications on AWS

Ricardo Sueiras

Principal Technologist

API Gateway

 

 

• Amazon API Gateway: a managed service for building APIs.
• Design, deploy, manage, and secure your APIs.

Amazon API Gateway capabilities

 

• Implement different types of API.

Amazon API Gateway capabilities

 

• Implement different types of API.
• Integrate with backend services.

Amazon API Gateway capabilities

 

• Implement different types of API.
• Integrate with backend services.
• Secure access to APIs.

Amazon API Gateway capabilities

 

• Implement different types of API.
• Integrate with backend services.
• Secure access to APIs.
• Throttle requests to protect backends.

Amazon API Gateway capabilities

 

• Implement different types of API.
• Integrate with backend services.
• Secure access to APIs.
• Throttle requests to protect backends.
• Transform request and response payloads.

Amazon API Gateway capabilities

 

• Implement different types of API.
• Integrate with backend services.
• Secure access to APIs.
• Throttle requests to protect backends.
• Transform request and response payloads.
• Publish APIs for consumers.

Amazon API Gateway capabilities

 

• Implement different types of API.
• Integrate with backend services.
• Secure access to APIs.
• Throttle requests to protect backends.
• Transform request and response payloads.
• Publish APIs for consumers.
• Manage the API lifecycle: versioning, deployment, aliases.

API types

• API Gateway supports three API types:
  • REST APIs
  • HTTP APIs
  • WebSocket APIs

 

API Gateway endpoints

• Endpoints control how clients reach your API.
• Edge-optimized: AWS-managed CloudFront for global low latency.
• Regional: deployed into a specific AWS Region.
• Private: reachable only via AWS PrivateLink.
• Private endpoints stay off the public internet.

 

REST APIs

• Most feature-rich API Gateway offering.
• Built on a synchronous request/response model.

 

REST API use cases

 

• Enterprise APIs needing full life-cycle management.
• APIs requiring advanced security controls.
• Third-party developer ecosystems with API keys and usage plans.
• Direct AWS service integrations without Lambda.

API Gateway REST API support

 

• Request validation.
• API keys.
• Usage plans and throttling.
• Response caching with configurable TTL.
• Request/response transformation via VTL templates.
• IAM authentication (Signature V4).
• Lambda authorizers, Cognito user pools.

API Gateway REST API support

 

 

• Three endpoint types supported:
  • Edge-optimized
  • Regional
  • Private
• Web exploit protection with AWS WAF.
• Canary release deployments.
• Observability via AWS X-Ray and CloudWatch logging.

REST APIs trade-offs

• More expensive than HTTP APIs.
• Slightly higher latency.

 

HTTP APIs

• Optimized for performance and cost over feature breadth:
  • Performance
  • Cost

 

HTTP API use cases

• Serverless workloads and Lambda-backed APIs.
• Microservices and lightweight proxy APIs.
• Latency-sensitive applications.
• APIs using OAuth 2.0 / OIDC authentication.

 

API Gateway HTTP API support

 

• Lambda proxy integrations and authorizers.
• Native JWT/OIDC authorization (Cognito, Auth0, Okta).
• Built-in CORS configuration at the API level.
• Private VPC integrations via VPC Link.
• Basic parameter mapping for headers, query strings, and paths.

HTTP API trade-offs

 

• HTTP APIs do NOT support:

  • API keys
  • Usage plans
  • Request validation
  • Response caching
  • Tracing with AWS X-Ray

  • VTL payload transformation

  • Only support:

    • Edge or private endpoints (regional only)

WebSocket APIs

 

• Two-way communication between clients and servers.
• Connection stays open, unlike REST and HTTP APIs.
• Servers can push data to connected clients.

WebSocket API use cases

• Chat applications.
• Real-time notifications.
• Real-time dashboards.

 

API Gateway WebSocket API support

• Payload data transformations.
• Request validation.
• Special built-in routes:
  • $connect: client establishes a connection
  • $disconnect: client disconnects
  • $default: no matching route found

 

API caching

• Caching responses reduces backend load.
• Improves API performance.
• Typical use cases:
  • Frequently requested data
  • Read-heavy APIs
  • Reducing Lambda invocations

 

API caching

 

• Cached responses expire after a configurable TTL.
• Manage stale data by:
  • Setting the cache to expire
  • Flushing the cache

API design best practices: use clear resource naming

 

• Paths should represent resources, not actions.
• Use nouns, not verbs.
• Good:
  • GET /orders/123
• Avoid:
  • GET /getOrder/123

API design best practices: version APIs

 

• Version APIs to evolve them safely over time.
• Avoid breaking existing clients.
• Common approaches:
  • URI versioning: GET /v1/orders
  • Query parameter: GET /orders?version=1
  • HTTP header: Accept-Version: v1

API developer portals

• Publish and share REST APIs via a web portal.
• Provide documentation to API consumers.
• Key features:
  • API documentation (Swagger files)
  • Consumer onboarding
  • SDK downloads
  • API key registration and subscription flows

 

OpenAPI specifications

• OpenAPI (Swagger): the standard way to describe REST APIs.
• API Gateway can import and export OpenAPI specs.

 

Let's practice!

Developing applications on AWS