API Gateway

drive-apig uses one Terraform-managed API Gateway REST API per stage. Serverless services attach resources and methods to that shared API by reading the REST API id and root resource id from SSM.

Shared REST API

The REST API is created in Terraform, not by an individual Serverless service:

resource "aws_api_gateway_rest_api" "apig_rest_api" {
  name        = local.api_name
  description = "Drive API Gateway"
  minimum_compression_size = 100
  endpoint_configuration {
    types = ["EDGE"]
  }
}

Terraform publishes the identifiers to SSM:

/${environment}/${client_code}/apig/${client_app_name}/id
/${environment}/${client_code}/apig/${client_app_name}/root_resource_id

Shared Serverless config consumes those values:

provider:
  apiGateway:
    restApiId: ${ssm:/${self:provider.stage}/drive/apig/drive-api/id}
    restApiRootResourceId: ${ssm:/${self:provider.stage}/drive/apig/drive-api/root_resource_id}
    metrics: true
    apiKeys:
      - ${self:provider.stage}-${self:service}-api-key
      - ${self:provider.stage}-${self:service}-api-key-external

Some services redeclare the same SSM values locally when they do not include the shared block. The ownership model is still the same: Terraform owns the REST API; each service owns its paths, methods, handlers, and stack.

Custom domains

The API Gateway domain name, Route53 alias, stage, deployment, and base-path mapping are defined in platform/terraform/env-*/main.apig.tf. Dev and staging use the non-prod account; prod uses the prod account.

Method auth

private: true on a Serverless HTTP event requires X-Api-Key. private: false makes the API Gateway method public, though the handler can still enforce its own token, signature, host, or payload checks.

See Auth & API keys for the route-level convention.

Caching and metrics

The stage has cache and metrics enabled in Terraform. Individual service methods opt into method caching with apiGatewayCaching or a per-event caching block.

Examples of cacheable routes include /geo/city, /leads/custom-finance/{stockId}, social count routes, and selected syndication feeds. Do not infer cache behavior from route name alone; check the owning services/<service>/serverless.yml.