AwsApiGateway

Service-level API Gateway component that supports either HTTP (v2) or REST (v1) APIs.

Remarks

This is the primary public component resource for API Gateway in this package. Each component instance creates exactly one API type.

Naming:

• Root: type ${namespace}:aws:AwsApiGateway; capability apigateway; identity args.identity; target ${env}-${projectHash}-apigateway-${sanitiseNamePart(identity)}. A punctuation-only identity such as ___ is rejected; the identity must contain an alphanumeric character.

• HTTP single children: aws:apigatewayv2/api:Api, aws:apigatewayv2/stage:Stage, aws:apigatewayv2/domainName:DomainName, aws:apigatewayv2/apiMapping:ApiMapping, and aws:wafv2/webAclAssociation:WebAclAssociation have parent AwsApiGateway, tuple [args.identity], and target ${env}-${projectHash}-${sanitiseNamePart(identity)}.

• HTTP repeated children have parent AwsApiGateway and use the keyed-collection map key as their sole discriminator (the map key IS the identity): aws:apigatewayv2/authorizer:Authorizer uses tuple [args.identity, args.http.authorizers.<key>]; aws:apigatewayv2/integration:Integration and aws:apigatewayv2/route:Route (one integration and one route per route entry) use tuple [args.identity, args.http.routes.<key>]. A group-wide collision preflight runs over every candidate name before any authorizer/route/integration is constructed.

• REST single children: aws:apigateway/restApi:RestApi, aws:apigateway/deployment:Deployment, aws:apigateway/stage:Stage, aws:apigateway/domainName:DomainName, aws:apigateway/basePathMapping:BasePathMapping, and aws:wafv2/webAclAssociation:WebAclAssociation have parent AwsApiGateway, tuple [args.identity], and target ${env}-${projectHash}-${sanitiseNamePart(identity)}.

• REST repeated children have parent AwsApiGateway. aws:apigateway/method:Method and aws:apigateway/integration:Integration (one method and one integration per route entry) use tuple [args.identity, args.rest.routes.<key>], where the map key is the RAW <METHOD> <path> route key (NOT the provider-normalised method/path); a group-wide collision preflight runs over every candidate name before any method/integration is constructed. aws:apigateway/resource:Resource uses tuple [args.identity, <resolved path>], where the second discriminator is the resolved nested path with its leading slash removed (for example GET /v1/users contributes the path keys v1 and v1/users). Nested path resources are shared across route entries and have no consumer-provided per-resource map key, so their stable identity is this resolved-path key derived from the args.rest.routes keys; a group-wide collision preflight runs over every path key before any resource is constructed.

• Lambda invoke permissions are owned by the referenced Lambda component. This component supplies source-side relationship identities only: custom authorizers use [args.identity, args.http.authorizers.<key>]; HTTP and REST route integrations use [args.identity, stable suffix of args.<capability>.routes.<key>]. The Lambda component separately adds the function identity and invoking-service discriminator.

• AWS provider names (semantic/external, forwarded unchanged; AWS owns constraints and validation):

  • HTTP Api.name and REST RestApi.name use the stackOnly style ${env}-${projectHash} (fixed result); they carry no purpose and the component proves the fixed value.
  • HTTP authorizer Authorizer.name (source args.http.authorizers.<key>.name) is forwarded unchanged. REST has no authorizer resource.
  • HTTP Stage.name (source args.http.stageName, default $default) and REST Stage.stageName (source args.rest.stageName, default v1) are forwarded unchanged.
  • Custom-domain domainName (source args.<capability>.customDomain.domainName) is a semantic DNS identifier forwarded unchanged; the HTTP API mapping key (source args.http.customDomain.apiMappingKey) and REST base path (source args.rest.customDomain.basePath) are semantic identifiers forwarded unchanged. Other children have no controlled provider name. The AWS six-style standard does not apply to these semantic identifiers.

Example

const httpApi = new AwsApiGateway({
  identity: 'http-api',
  type: 'HTTP',
  http: {
    routes: {
      'GET /health': {
        integration: {
          type: 'lambda',
          targetArn: lambdaFunction.arn,
          createInvokePermission: false,
        },
      },
    },
  },
});

const restApi = new AwsApiGateway({
  identity: 'rest-api',
  type: 'REST',
  rest: {
    customDomain: {
      domainName: 'api.example.com',
      endpointType: 'REGIONAL',
      securityPolicy: 'SecurityPolicy_TLS13_1_3_2025_09',
      endpointAccessMode: 'BASIC',
      certificate: {
        regionalCertificateArn: regionalCertificate.arn,
      },
    },
    routes: {
      'GET /v1/users': {
        integration: {
          type: 'lambda',
          targetArn: usersFunction.arn,
          createInvokePermission: false,
        },
      },
    },
  },
});

Constructors

new AwsApiGateway( args: AwsApiGatewayArgs, options?: ComponentResourceOptions, ): AwsApiGateway

Parameters

• args (AwsApiGatewayArgs) — API Gateway capability inputs for either HTTP API (v2) or REST API (v1).
• options (ComponentResourceOptions, optional) — Optional settings controlling resource behaviour.

Returns

AwsApiGateway

Hierarchy

• ComponentResource
• AwsApiGateway

Properties

apiArn: Output<string>

API ARN.

apiId: Output<string>

API identifier.

customDomainName: Output<string>

Custom domain name, when configured for HTTP or REST capability.

customDomainTargetDomainName: Output<string>

API Gateway custom-domain target domain name, when configured for HTTP or REST capability.

customDomainTargetZoneId: Output<string>

API Gateway custom-domain target hosted zone ID, when configured for HTTP or REST capability.

executionArn: Output<string>

API execution ARN prefix.

invokeUrl: Output<string>

Stage invoke URL.

lambdaInvokePermissions: Resource[]

Lambda invoke permissions created for managed integrations and authorizers.

stageName: Output<string>

Stage name for the created API.

type: 'HTTP' | 'REST'

Effective API type created by this component.

urn: Output<string>

Inherited from urn

The stable logical URN used to distinctly address a resource, both before and after deployments.

wafAttachment: WebAclAssociation

Optional WAFv2 web ACL association created for the API stage.

webAclAssociation: WebAclAssociation

Optional WAFv2 web ACL association created for the API stage.

Methods

getData(): Promise<any>

Inherited from getData

Retrieves the data produces by initialize. The data is immediately available in a derived class's constructor after the super(...) call to ComponentResource.

Returns

• Promise<any>

getProvider(moduleMember: string): ProviderResource | undefined

Inherited from getProvider

Returns the provider for the given module member, if one exists.

Parameters

• moduleMember (string)

Returns

• ProviderResource | undefined

initialize( args: Inputs, opts?: ComponentResourceOptions, name?: string, type?: string, ): Promise<any>

Inherited from initialize

Can be overridden by a subclass to asynchronously initialize data for this component automatically when constructed. The data will be available immediately for subclass constructors to use. To access the data use getData.

Parameters

• args (Inputs)
• opts (ComponentResourceOptions, optional)
• name (string, optional)
• type (string, optional)

Returns

• Promise<any>

registerOutputs( outputs?: Inputs | Promise<Inputs> | Output<Inputs>, ): void

Inherited from registerOutputs

Registers synthetic outputs that a component has initialized, usually by allocating other child sub-resources and propagating their resulting property values.

Component resources can call this at the end of their constructor to indicate that they are done creating child resources. This is not strictly necessary as this will automatically be called after the initialize method completes.

Parameters

• outputs (Inputs | Promise<Inputs> | Output<Inputs>, optional)

Returns

• void

Static Methods

isInstance(obj: any): obj is ComponentResource<any>

Inherited from isInstance

Returns true if the given object is a CustomResource. This is designed to work even when multiple copies of the Pulumi SDK have been loaded into the same process.

Parameters

• obj (any)

Returns

• obj is ComponentResource<any>