rest_apis

Creates, updates, deletes or gets a rest_api resource or lists rest_apis in a region

Overview

Name	rest_apis
Type	Resource
Description	The AWS::ApiGateway::RestApi resource creates a REST API. For more information, see restapi:create in the Amazon API Gateway REST API Reference. On January 1, 2016, the Swagger Specification was donated to the OpenAPI initiative, becoming the foundation of the OpenAPI Specification.
Id	awscc.apigateway.rest_apis

Fields

get (all properties)

Name	Datatype	Description
policy	object	A policy document that contains the permissions for the RestApi resource. To set the ARN for the policy, use the !Join intrinsic function with "" as delimiter and values of "execute-api:/" and "*".
▶body_s3_location	object	The Amazon Simple Storage Service (Amazon S3) location that points to an OpenAPI file, which defines a set of RESTful APIs in JSON or YAML format.
description	string
minimum_compression_size	integer
parameters	object
clone_from	string
mode	string	This property applies only when you use OpenAPI to define your REST API. The Mode determines how API Gateway handles resource updates. Valid values are overwrite or merge. For overwrite, the new API definition replaces the existing one. The existing API identifier remains unchanged. For merge, the new API definition is merged with the existing API. If you don't specify this property, a default value is chosen. For REST APIs created before March 29, 2021, the default is overwrite. For REST APIs created after March 29, 2021, the new API definition takes precedence, but any container types such as endpoint configurations and binary media types are merged with the existing API. Use the default mode to define top-level RestApi properties in addition to using OpenAPI. Generally, it's preferred to use API Gateway's OpenAPI extensions to model these properties.
rest_api_id	string
disable_execute_api_endpoint	boolean
fail_on_warnings	boolean
binary_media_types	array
name	string	The name of the RestApi. A name is required if the REST API is not based on an OpenAPI specification.
root_resource_id	string
api_key_source_type	string
▶endpoint_configuration	object	A list of the endpoint types of the API. Use this property when creating an API. When importing an existing API, specify the endpoint configuration types using the Parameters property.
body	object	An OpenAPI specification that defines a set of RESTful APIs in JSON format. For YAML templates, you can also provide the specification in YAML format.
▶tags	array
region	string	AWS region.

list (identifiers only)

Name	Datatype	Description
rest_api_id	string
region	string	AWS region.

For more information, see AWS::ApiGateway::RestApi.

Methods

Name	Resource	Accessible by	Required Params
create_resource	rest_apis	INSERT	region
delete_resource	rest_apis	DELETE	Identifier, region
update_resource	rest_apis	UPDATE	Identifier, PatchDocument, region
list_resources	rest_apis_list_only	SELECT	region
get_resource	rest_apis	SELECT	Identifier, region

SELECT examples

get (all properties)

Gets all properties from an individual rest_api.

SELECT
  region,
  policy,
  body_s3_location,
  description,
  minimum_compression_size,
  parameters,
  clone_from,
  mode,
  rest_api_id,
  disable_execute_api_endpoint,
  fail_on_warnings,
  binary_media_types,
  name,
  root_resource_id,
  api_key_source_type,
  endpoint_configuration,
  body,
  tags
FROM awscc.apigateway.rest_apis
WHERE
  region = '{{ region }}' AND
  Identifier = '{{ rest_api_id }}';

list (identifiers only)

Lists all rest_apis in a region.

SELECT
  region,
  rest_api_id
FROM awscc.apigateway.rest_apis_list_only
WHERE
  region = '{{ region }}';

INSERT example

Use the following StackQL query and manifest file to create a new rest_api resource, using stack-deploy.

Required Properties

/*+ create */
INSERT INTO awscc.apigateway.rest_apis (
  Policy,
  BodyS3Location,
  Description,
  MinimumCompressionSize,
  Parameters,
  CloneFrom,
  Mode,
  DisableExecuteApiEndpoint,
  FailOnWarnings,
  BinaryMediaTypes,
  Name,
  ApiKeySourceType,
  EndpointConfiguration,
  Body,
  Tags,
  region
)
SELECT
  '{{ policy }}',
  '{{ body_s3_location }}',
  '{{ description }}',
  '{{ minimum_compression_size }}',
  '{{ parameters }}',
  '{{ clone_from }}',
  '{{ mode }}',
  '{{ disable_execute_api_endpoint }}',
  '{{ fail_on_warnings }}',
  '{{ binary_media_types }}',
  '{{ name }}',
  '{{ api_key_source_type }}',
  '{{ endpoint_configuration }}',
  '{{ body }}',
  '{{ tags }}',
  '{{ region }}'
RETURNING
  ErrorCode,
  EventTime,
  Identifier,
  Operation,
  OperationStatus,
  RequestToken,
  ResourceModel,
  RetryAfter,
  StatusMessage,
  TypeName
;

All Properties

/*+ create */
INSERT INTO awscc.apigateway.rest_apis (
  Policy,
  BodyS3Location,
  Description,
  MinimumCompressionSize,
  Parameters,
  CloneFrom,
  Mode,
  DisableExecuteApiEndpoint,
  FailOnWarnings,
  BinaryMediaTypes,
  Name,
  ApiKeySourceType,
  EndpointConfiguration,
  Body,
  Tags,
  region
)
SELECT
  '{{ policy }}',
  '{{ body_s3_location }}',
  '{{ description }}',
  '{{ minimum_compression_size }}',
  '{{ parameters }}',
  '{{ clone_from }}',
  '{{ mode }}',
  '{{ disable_execute_api_endpoint }}',
  '{{ fail_on_warnings }}',
  '{{ binary_media_types }}',
  '{{ name }}',
  '{{ api_key_source_type }}',
  '{{ endpoint_configuration }}',
  '{{ body }}',
  '{{ tags }}',
  '{{ region }}'
RETURNING
  ErrorCode,
  EventTime,
  Identifier,
  Operation,
  OperationStatus,
  RequestToken,
  ResourceModel,
  RetryAfter,
  StatusMessage,
  TypeName
;

Manifest

version: 1
name: stack name
description: stack description
providers:
- aws
globals:
- name: region
  value: '{{ vars.AWS_REGION }}'
resources:
- name: rest_api
  props:
    - name: policy
      value: {}
    - name: body_s3_location
      value:
        bucket: '{{ bucket }}'
        e_tag: '{{ e_tag }}'
        version: '{{ version }}'
        key: '{{ key }}'
    - name: description
      value: '{{ description }}'
    - name: minimum_compression_size
      value: '{{ minimum_compression_size }}'
    - name: parameters
      value: {}
    - name: clone_from
      value: '{{ clone_from }}'
    - name: mode
      value: '{{ mode }}'
    - name: disable_execute_api_endpoint
      value: '{{ disable_execute_api_endpoint }}'
    - name: fail_on_warnings
      value: '{{ fail_on_warnings }}'
    - name: binary_media_types
      value:
        - '{{ binary_media_types[0] }}'
    - name: name
      value: '{{ name }}'
    - name: api_key_source_type
      value: '{{ api_key_source_type }}'
    - name: endpoint_configuration
      value:
        ip_address_type: '{{ ip_address_type }}'
        types:
          - '{{ types[0] }}'
        vpc_endpoint_ids:
          - '{{ vpc_endpoint_ids[0] }}'
    - name: body
      value: {}
    - name: tags
      value:
        - value: '{{ value }}'
          key: '{{ key }}'

UPDATE example

Use the following StackQL query and manifest file to update a rest_api resource, using stack-deploy.

/*+ update */
UPDATE awscc.apigateway.rest_apis
SET PatchDocument = string('{{ {
    "Policy": policy,
    "BodyS3Location": body_s3_location,
    "Description": description,
    "MinimumCompressionSize": minimum_compression_size,
    "Parameters": parameters,
    "CloneFrom": clone_from,
    "Mode": mode,
    "DisableExecuteApiEndpoint": disable_execute_api_endpoint,
    "FailOnWarnings": fail_on_warnings,
    "BinaryMediaTypes": binary_media_types,
    "Name": name,
    "ApiKeySourceType": api_key_source_type,
    "EndpointConfiguration": endpoint_configuration,
    "Body": body,
    "Tags": tags
} | generate_patch_document }}')
WHERE
  region = '{{ region }}' AND
  Identifier = '{{ rest_api_id }}'
RETURNING
  ErrorCode,
  EventTime,
  Identifier,
  Operation,
  OperationStatus,
  RequestToken,
  ResourceModel,
  RetryAfter,
  StatusMessage,
  TypeName
;

DELETE example

/*+ delete */
DELETE FROM awscc.apigateway.rest_apis
WHERE
  Identifier = '{{ rest_api_id }}' AND
  region = '{{ region }}'
RETURNING
  ErrorCode,
  EventTime,
  Identifier,
  Operation,
  OperationStatus,
  RequestToken,
  ResourceModel,
  RetryAfter,
  StatusMessage,
  TypeName
;

Additional Parameters

Mutable resources in the Cloud Control provider support additional optional parameters which can be supplied with INSERT, UPDATE, or DELETE operations. These include:

Parameter	Description
ClientToken	A unique identifier to ensure the idempotency of the resource request. This allows the provider to accurately distinguish between retries and new requests. A client token is valid for 36 hours once used. After that, a resource request with the same client token is treated as a new request. If you do not specify a client token, one is generated for inclusion in the request.
RoleArn	The ARN of the IAM role used to perform this resource operation. The role specified must have the permissions required for this operation. If you do not specify a role, a temporary session is created using your AWS user credentials.
TypeVersionId	For private resource types, the type version to use in this resource operation. If you do not specify a resource version, the default version is used.

Permissions

To operate on the rest_apis resource, the following permissions are required:

Read

apigateway:GET

Create

apigateway:GET,
apigateway:POST,
apigateway:PUT,
apigateway:PATCH,
apigateway:UpdateRestApiPolicy,
s3:GetObject,
iam:PassRole

Update

apigateway:GET,
apigateway:DELETE,
apigateway:PATCH,
apigateway:PUT,
apigateway:UpdateRestApiPolicy,
s3:GetObject,
iam:PassRole

List

apigateway:GET

Delete

apigateway:DELETE