The following use case shows how to enforce management control for Amazon API Gateway governance using the following controls:

• Freeze API modifications based on a tag
• Prevent custom domains in child accounts (enforce central API service account)
• Prevent public APIs in accounts other than the central API/service account
• Require all resources to have tags
• Require error responses to have custom messages
• Require API has documentation
• Require response payload compression is enabled

Freeze API modifications based on a tag

Preventative controls

Use a service control policy (SCP) with condition key aws:ResourceTag/${TagKey} to enforce this requirement. This policy does not allow changing a tag value that was used to freeze the resource in the first place. To lift the freeze, the AWS Identity and Access Management (IAM) policy must be be temporarily disabled or modified to include exceptions. The following example prevents any actions on an API Gateway resources with tag EnvironmentState value frozen.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "Statement1",
      "Effect": "Deny",
      "Action": [
        "apigateway:DELETE",
        "apigateway:PATCH",
        "apigateway:POST",
        "apigateway:PUT"
      ],
      "Resource": "*",
      "Condition":{
      "StringEquals":{"aws:ResourceTag/EnvironmentState": "frozen"}
      }
    }
  ]
}

Note: As an alternative, consider freezing deployments based on a stage name. For example, deny all deployments to a particular stage using condition apigateway:Request/StageName..

Detective controls

Amazon EventBridge rule or AWS Config custom AWS Lambda rule

Prevent custom domains in child accounts (enforce central API service account)

Context

• Setting up custom domain names for REST APIs
• Amazon API Gateway API Reference - CreateDomainName
• Architecting multiple microservices behind a single domain with Amazon API Gateway

Note: Can use approach to prevent public APIs in child accounts as described later in this section, or in combination with this one.

Preventative controls

SCP that prevents any actions on a DomainName resource in child accounts can be used to enforce this requirement. For example, the following policy prevents creating new or updating existing domain names:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "Statement1",
      "Effect": "Deny",
      "Action": [
        "apigateway:PUT",
        "apigateway:PATCH",
        "apigateway:POST"
      ],
      "Resource": [
        "arn:aws:apigateway:*::/domainnames",
        "arn:aws:apigateway:*::/domainnames/*"
      ]
    }
  ]
}

Detective controls

Amazon EventBridge rule or AWS Config custom AWS Lambda rule

Prevent public APIs in accounts other than the central API/service account

Context

• Choose an endpoint type for an API Gateway API

Preventative controls

SCP to be applied to the accounts other than central API/service account that requires condition apigateway:Request/EndpointType to have value EDGE or REGIONAL. See example IAM policy in documentation.

Detective controls

AWS Config rule - https://docs.aws.amazon.com/config/latest/developerguide/api-gw-endpoint-type-check.html

Require all resources to have tags

Context

• Tagging your API Gateway resources
• Tag policies

Preventative controls

SCP that uses condition aws:ResourceTag and prevents any actions on any API Gateway resource that does not have a tag with a particular name and, optionally, a value that can be used to enforce this requirement. For example, the following policy denies all create/edit actions on API Gateway if tag owner is missing:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "Statement1",
            "Effect": "Deny",
            "Action": [
                "apigateway:PATCH",
                "apigateway:POST",
                "apigateway:PUT"
            ],
            "Resource": [
                "arn:aws:apigateway:*::/restapis/*"
            ],
            "Condition": {
                "Null": {
                    "aws:ResourceTag/owner": "true"
                }
            }
        }
    ]
}

Note that child resources of RestApi, DomainName, and UsagePlan inherit tags of the parent.

Detective controls

Amazon EventBridge rule or AWS Config custom lambda rule

As an alternative, you can use AWS Organizations tag policies that allow you to maintain consistent tags, including the preferred case treatment of tag keys and tag values.

Require error responses to have custom messages

Context

• Gateway responses in API Gateway
• Amazon API Gateway API Reference - MethodResponse - responseModels

Preventative controls

N/A. IAM and SCPs for API Gateway do not have conditions related to the MethodResponse resource.

Detective controls

Amazon EventBridge rule or AWS Config custom AWS Lambda rule

Require API to have documentation

Context

• Documenting REST APIs
• Amazon API Gateway API Reference - CreateDocumentationPart
• Amazon API Gateway API Reference - CreateDocumentationVersion

Preventative controls

N/A. IAM and SCPs for API Gateway do not have conditions related to the DocumentationPart or DocumentationVersion resources.

Proactive controls

Custom AWS CloudFormation Hook.

Detective controls

AWS Config custom rule using Guard, enabled for all AWS::ApiGateway::Stage resources:

rule apigw_documentation_present_check when
    resourceType == "AWS::ApiGateway::Stage"
    {
        configuration.documentationVersion is_string
    }

Require response payload compression is enabled

Context

• Enabling payload compression for an API
• Amazon API Gateway API Reference - CreateRestApi - minimumCompressionSize

Preventative controls

N/A. IAM and SCPs for API Gateway do not have compression related conditions for the RestApi resource

Proactive controls

Custom AWS CloudFormation Hook.

Detective controls

AWS Config custom rule using Guard, enabled for all AWS::ApiGateway::RestApi resources:

rule apigw_compression_enabled_check when
    resourceType == "AWS::ApiGateway::RestApi"
    {
        configuration.minimumCompressionSize >= 0
    }