"""
Connection module for Amazon APIGateway using boto3.
====================================================
Renamed from ``boto_apigateway`` to ``boto3_apigateway`` and rewritten to use the
boto3 ``apigateway`` client APIs directly via
:py:mod:`saltext.boto3.utils.boto3mod`. The legacy boto2 code path
(object-style access, retry loops) has been removed.
:depends:
- boto3 >= 1.28.0
- botocore >= 1.31.0
:configuration: This module accepts explicit API Gateway credentials but can also
utilize IAM roles assigned to the instance through Instance Profiles.
Dynamic credentials are then automatically obtained from AWS API and no
further configuration is necessary. More Information available at:
.. code-block:: text
http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam-roles-for-amazon-ec2.html
If IAM roles are not used you need to specify them either in a pillar or
in the minion's config file:
.. code-block:: yaml
apigateway.keyid: GKTADJGHEIQSXMKKRBJ08H
apigateway.key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs
A region may also be specified in the configuration:
.. code-block:: yaml
apigateway.region: us-west-2
If a region is not specified, the default is us-east-1.
It's also possible to specify key, keyid and region via a profile, either
as a passed in dict, or as a string to pull from pillars or minion config:
.. code-block:: yaml
myprofile:
keyid: GKTADJGHEIQSXMKKRBJ08H
key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs
region: us-west-2
.. versionadded:: 1.0.0
"""
import datetime
import logging
import salt.utils.json
from saltext.boto3.utils import boto3mod
try:
from botocore.exceptions import ClientError
logging.getLogger("boto3").setLevel(logging.CRITICAL)
HAS_BOTO3 = True
except ImportError:
HAS_BOTO3 = False
log = logging.getLogger(__name__)
__virtualname__ = "boto3_apigateway"
def _get_conn(service, region=None, key=None, keyid=None, profile=None):
"""
Return a boto3 client for ``service`` using this module's dunders.
"""
return boto3mod.get_connection(
service,
opts=__opts__,
context=__context__,
region=region,
key=key,
keyid=keyid,
profile=profile,
)
[docs]
def __virtual__():
"""
Only load if boto3 is available. Minimum version is enforced via the
project's ``pyproject.toml`` dependency declaration.
"""
if HAS_BOTO3:
return __virtualname__
return (False, "The boto3_apigateway module could not be loaded: boto3 is not available.")
def _convert_datetime_str(response):
"""
modify any key-value pair where value is a datetime object to a string.
"""
if response:
return {k: f"{v}" if isinstance(v, datetime.date) else v for k, v in response.items()}
return None
def _filter_apis(name, apis):
"""
Return list of api items matching the given name.
"""
return [api for api in apis if api["name"] == name]
def _filter_apis_desc(desc, apis):
"""
Return list of api items matching the given description.
"""
return [api for api in apis if api["description"] == desc]
def _multi_call(function, contentkey, *args, **kwargs):
"""
Retrieve full list of values for the contentkey from a boto3 ApiGateway
client function that may be paged via 'position'
"""
ret = function(*args, **kwargs)
position = ret.get("position")
while position:
more = function(*args, position=position, **kwargs)
ret[contentkey].extend(more[contentkey])
position = more.get("position")
return ret.get(contentkey)
def _find_apis_by_name(name, description=None, region=None, key=None, keyid=None, profile=None):
"""
get and return list of matching rest api information by the given name and desc.
If rest api name evaluates to False, return all apis w/o filtering the name.
"""
try:
conn = _get_conn("apigateway", region=region, key=key, keyid=keyid, profile=profile)
apis = _multi_call(conn.get_rest_apis, "items")
if name:
apis = _filter_apis(name, apis)
if description is not None:
apis = _filter_apis_desc(description, apis)
return {"restapi": [_convert_datetime_str(api) for api in apis]}
except ClientError as e:
return {"error": boto3mod.get_error(e)}
[docs]
def describe_apis(name=None, description=None, region=None, key=None, keyid=None, profile=None):
"""
Returns all rest apis in the defined region. If optional parameter name is included,
returns all rest apis matching the name in the defined region.
name (str, optional):
The name of the REST API to filter by. If not provided, all APIs are returned.
description (str, optional):
The description of the REST API to filter by. If not provided, all APIs are returned.
region (str, optional):
The AWS region where the REST APIs are located.
key (str, optional):
The AWS secret access key.
keyid (str, optional):
The AWS access key ID.
profile (str, optional):
The profile to use for AWS credentials.
CLI Example:
.. code-block:: bash
salt myminion boto3_apigateway.describe_apis
salt myminion boto3_apigateway.describe_apis name='api name'
salt myminion boto3_apigateway.describe_apis name='api name' description='desc str'
"""
if name:
return _find_apis_by_name(
name,
description=description,
region=region,
key=key,
keyid=keyid,
profile=profile,
)
else:
return _find_apis_by_name(
"",
description=description,
region=region,
key=key,
keyid=keyid,
profile=profile,
)
[docs]
def api_exists(name, description=None, region=None, key=None, keyid=None, profile=None):
"""
Check to see if the given Rest API Name and optionally description exists.
name (str):
The name of the REST API to check for existence.
description (str, optional):
The description of the REST API to check for existence.
region (str, optional):
The AWS region where the REST APIs are located.
key (str, optional):
The AWS secret access key.
keyid (str, optional):
The AWS access key ID.
profile (str, optional):
The profile to use for AWS credentials.
CLI Example:
.. code-block:: bash
salt myminion boto3_apigateway.api_exists name='myapi_name'
"""
apis = _find_apis_by_name(
name,
description=description,
region=region,
key=key,
keyid=keyid,
profile=profile,
)
return {"exists": bool(apis.get("restapi"))}
[docs]
def create_api(name, description, cloneFrom=None, region=None, key=None, keyid=None, profile=None):
"""
Create a new REST API Service with the given name
name (str):
The name of the REST API to create.
description (str):
The description of the REST API to create.
cloneFrom (str, optional):
The ID of an existing REST API to clone. If not provided, a new API is created.
region (str, optional):
The AWS region where the REST API is to be created.
key (str, optional):
The AWS secret access key.
keyid (str, optional):
The AWS access key ID.
profile (str, optional):
The profile to use for AWS credentials.
CLI Example:
.. code-block:: bash
salt myminion boto3_apigateway.create_api name='myapi_name' description='api_description'
"""
try:
conn = _get_conn("apigateway", region=region, key=key, keyid=keyid, profile=profile)
if cloneFrom:
api = conn.create_rest_api(name=name, description=description, cloneFrom=cloneFrom)
else:
api = conn.create_rest_api(name=name, description=description)
api = _convert_datetime_str(api)
return {"created": True, "restapi": api} if api else {"created": False}
except ClientError as e:
return {"created": False, "error": boto3mod.get_error(e)}
[docs]
def delete_api(name, description=None, region=None, key=None, keyid=None, profile=None):
"""
Delete all REST API Service with the given name and an optional API description
name (str):
The name of the REST API to delete.
description (str, optional):
The description of the REST API to delete.
region (str, optional):
The AWS region where the REST API is located.
key (str, optional):
The AWS secret access key.
keyid (str, optional):
The AWS access key ID.
profile (str, optional):
The profile to use for AWS credentials.
CLI Example:
.. code-block:: bash
salt myminion boto3_apigateway.delete_api name='myapi_name'
salt myminion boto3_apigateway.delete_api name='myapi_name' description='api description'
"""
try:
conn_params = {"region": region, "key": key, "keyid": keyid, "profile": profile}
r = _find_apis_by_name(name, description=description, **conn_params)
apis = r.get("restapi")
if apis:
conn = boto3mod.get_connection(
"apigateway",
opts=__opts__,
context=__context__,
**conn_params,
)
for api in apis:
conn.delete_rest_api(restApiId=api["id"])
return {"deleted": True, "count": len(apis)}
else:
return {"deleted": False}
except ClientError as e:
return {"deleted": False, "error": boto3mod.get_error(e)}
[docs]
def describe_api_resources(restApiId, region=None, key=None, keyid=None, profile=None):
"""
Given rest api id, return all resources for this api.
restApiId (str):
The ID of the REST API for which to describe resources.
region (str, optional):
The AWS region where the REST API is located.
key (str, optional):
The AWS secret access key.
keyid (str, optional):
The AWS access key ID.
profile (str, optional):
The profile to use for AWS credentials.
CLI Example:
.. code-block:: bash
salt myminion boto3_apigateway.describe_api_resources restApiId='myapi_id'
"""
try:
conn = _get_conn("apigateway", region=region, key=key, keyid=keyid, profile=profile)
resources = sorted(
_multi_call(conn.get_resources, "items", restApiId=restApiId),
key=lambda k: k["path"],
)
return {"resources": resources}
except ClientError as e:
return {"error": boto3mod.get_error(e)}
[docs]
def describe_api_resource(restApiId, path, region=None, key=None, keyid=None, profile=None):
"""
Given rest api id, and an absolute resource path, returns the resource id for
the given path.
restApiId (str):
The ID of the REST API for which to describe the resource.
path (str):
The absolute path of the resource to describe.
region (str, optional):
The AWS region where the REST API is located.
key (str, optional):
The AWS secret access key.
keyid (str, optional):
The AWS access key ID.
profile (str, optional):
The profile to use for AWS credentials.
CLI Example:
.. code-block:: bash
salt myminion boto3_apigateway.describe_api_resource restApiId='myapi_id' path='resource_path'
"""
r = describe_api_resources(restApiId, region=region, key=key, keyid=keyid, profile=profile)
resources = r.get("resources")
if resources is None:
return r
for resource in resources:
if resource["path"] == path:
return {"resource": resource}
return {"resource": None}
[docs]
def create_api_resources(restApiId, path, region=None, key=None, keyid=None, profile=None):
"""
Given rest api id, and an absolute resource path, create all the resources and
return all resources in the resourcepath, returns False on failure.
restApiId (str):
The ID of the REST API for which to create the resources.
path (str):
The absolute path of the resource to create.
region (str, optional):
The AWS region where the REST API is located.
key (str, optional):
The AWS secret access key.
keyid (str, optional):
The AWS access key ID.
profile (str, optional):
The profile to use for AWS credentials.
CLI Example:
.. code-block:: bash
salt myminion boto3_apigateway.create_api_resources restApiId='myapi_id' path='resource_path'
"""
path_parts = path.split("/")
created = []
current_path = ""
try:
conn = _get_conn("apigateway", region=region, key=key, keyid=keyid, profile=profile)
for path_part in path_parts:
if current_path == "/":
current_path = f"{current_path}{path_part}"
else:
current_path = f"{current_path}/{path_part}"
r = describe_api_resource(
restApiId,
current_path,
region=region,
key=key,
keyid=keyid,
profile=profile,
)
resource = r.get("resource")
if not resource:
resource = conn.create_resource(
restApiId=restApiId, parentId=created[-1]["id"], pathPart=path_part
)
created.append(resource)
if created:
return {"created": True, "restApiId": restApiId, "resources": created}
else:
return {"created": False, "error": "unexpected error."}
except ClientError as e:
return {"created": False, "error": boto3mod.get_error(e)}
[docs]
def delete_api_resources(restApiId, path, region=None, key=None, keyid=None, profile=None):
"""
Given restApiId and an absolute resource path, delete the resources starting
from the absolute resource path. If resourcepath is the root resource '/',
the function will return False. Returns False on failure.
restApiId (str):
The ID of the REST API for which to delete the resources.
path (str):
The absolute path of the resource to delete.
region (str, optional):
The AWS region where the REST API is located.
key (str, optional):
The AWS secret access key.
keyid (str, optional):
The AWS access key ID.
profile (str, optional):
The profile to use for AWS credentials.
CLI Example:
.. code-block:: bash
salt myminion boto3_apigateway.delete_api_resources restApiId='myapi_id' path='resource_path'
"""
if path == "/":
return {"deleted": False, "error": "use delete_api to remove the root resource"}
try:
conn = _get_conn("apigateway", region=region, key=key, keyid=keyid, profile=profile)
r = describe_api_resource(
restApiId, path, region=region, key=key, keyid=keyid, profile=profile
)
resource = r.get("resource")
if resource:
conn.delete_resource(restApiId=restApiId, resourceId=resource["id"])
return {"deleted": True}
else:
return {"deleted": False, "error": f"no resource found by {path}"}
except ClientError as e:
return {"created": False, "error": boto3mod.get_error(e)}
[docs]
def describe_api_resource_method(
restApiId, resourcePath, httpMethod, region=None, key=None, keyid=None, profile=None
):
"""
Given rest api id, resource path, and http method (must be one of DELETE,
GET, HEAD, OPTIONS, PATCH, POST, PUT), return the method for the
api/resource path if defined. Return False if method is not defined.
restApiId (str):
The ID of the REST API for which to describe the resource method.
resourcePath (str):
The absolute path of the resource for which to describe the method.
httpMethod (str):
The HTTP method for the resource (must be one of DELETE, GET, HEAD, OPTIONS, PATCH, POST, PUT).
region (str, optional):
The AWS region where the REST API is located.
key (str, optional):
The AWS secret access key.
keyid (str, optional):
The AWS access key ID.
profile (str, optional):
The profile to use for AWS credentials.
CLI Example:
.. code-block:: bash
salt myminion boto3_apigateway.describe_api_resource_method restApiId='myapi_id' \
resourcePath='resource_path' httpMethod='httpmethod'
"""
r = describe_api_resource(
restApiId, resourcePath, region=region, key=key, keyid=keyid, profile=profile
)
resource = r.get("resource")
if not resource:
return {"error": "no such resource"}
try:
conn = _get_conn("apigateway", region=region, key=key, keyid=keyid, profile=profile)
method = conn.get_method(
restApiId=restApiId, resourceId=resource["id"], httpMethod=httpMethod
)
return {"method": method}
except ClientError as e:
return {"error": boto3mod.get_error(e)}
[docs]
def describe_api_key(apiKey, region=None, key=None, keyid=None, profile=None):
"""
Gets info about the given api key
apiKey (str):
The ID of the API key to describe.
region (str, optional):
The AWS region where the REST API is located.
key (str, optional):
The AWS secret access key.
keyid (str, optional):
The AWS access key ID.
profile (str, optional):
The profile to use for AWS credentials.
CLI Example:
.. code-block:: bash
salt myminion boto3_apigateway.describe_api_key apiKey='apigw_api_key'
"""
try:
conn = _get_conn("apigateway", region=region, key=key, keyid=keyid, profile=profile)
response = conn.get_api_key(apiKey=apiKey)
return {"apiKey": _convert_datetime_str(response)}
except ClientError as e:
return {"error": boto3mod.get_error(e)}
[docs]
def describe_api_keys(region=None, key=None, keyid=None, profile=None):
"""
Gets information about the defined API Keys. Return list of apiKeys.
region (str, optional):
The AWS region where the REST API is located.
key (str, optional):
The AWS secret access key.
keyid (str, optional):
The AWS access key ID.
profile (str, optional):
The profile to use for AWS credentials.
CLI Example:
.. code-block:: bash
salt myminion boto3_apigateway.describe_api_keys
"""
try:
conn = _get_conn("apigateway", region=region, key=key, keyid=keyid, profile=profile)
apikeys = _multi_call(conn.get_api_keys, "items")
return {"apiKeys": [_convert_datetime_str(apikey) for apikey in apikeys]}
except ClientError as e:
return {"error": boto3mod.get_error(e)}
[docs]
def create_api_key(
name,
description,
enabled=True,
stageKeys=None,
region=None,
key=None,
keyid=None,
profile=None,
):
"""
Create an API key given name and description.
An optional enabled argument can be provided. If provided, the
valid values are True|False. This argument defaults to True.
An optional stageKeys argument can be provided in the form of
list of dictionary with 'restApiId' and 'stageName' as keys.
name (str):
The name of the API key.
description (str):
The description of the API key.
enabled (bool, optional):
Whether the API key is enabled. Defaults to True.
stageKeys (list of dict, optional):
A list of stage key dictionaries, each containing 'restApiId' and 'stageName'.
region (str, optional):
The AWS region where the REST API is located.
key (str, optional):
The AWS secret access key.
keyid (str, optional):
The AWS access key ID.
profile (str, optional):
The profile to use for AWS credentials.
CLI Example:
.. code-block:: bash
salt myminion boto3_apigateway.create_api_key name description
salt myminion boto3_apigateway.create_api_key name description enabled=False
salt myminion boto3_apigateway.create_api_key name description \
stageKeys='[{"restApiId": "id", "stageName": "stagename"}]'
"""
try:
stageKeys = [] if stageKeys is None else stageKeys
conn = _get_conn("apigateway", region=region, key=key, keyid=keyid, profile=profile)
response = conn.create_api_key(
name=name, description=description, enabled=enabled, stageKeys=stageKeys
)
if not response:
return {"created": False}
return {"created": True, "apiKey": _convert_datetime_str(response)}
except ClientError as e:
return {"created": False, "error": boto3mod.get_error(e)}
[docs]
def delete_api_key(apiKey, region=None, key=None, keyid=None, profile=None):
"""
Deletes a given apiKey
apiKey (str):
The ID of the API key to delete.
region (str, optional):
The AWS region where the REST API is located.
key (str, optional):
The AWS secret access key.
keyid (str, optional):
The AWS access key ID.
profile (str, optional):
The profile to use for AWS credentials.
CLI Example:
.. code-block:: bash
salt myminion boto3_apigateway.delete_api_key apikeystring
"""
try:
conn = _get_conn("apigateway", region=region, key=key, keyid=keyid, profile=profile)
conn.delete_api_key(apiKey=apiKey)
return {"deleted": True}
except ClientError as e:
return {"deleted": False, "error": boto3mod.get_error(e)}
def _api_key_patch_replace(conn, apiKey, path, value):
"""
the replace patch operation on an ApiKey resource
"""
response = conn.update_api_key(
apiKey=apiKey, patchOperations=[{"op": "replace", "path": path, "value": value}]
)
return response
def _api_key_patchops(op, pvlist):
"""
helper function to return patchOperations object
"""
return [{"op": op, "path": p, "value": v} for (p, v) in pvlist]
def _api_key_patch_add(conn, apiKey, pvlist):
"""
the add patch operation for a list of (path, value) tuples on an ApiKey resource list path
"""
response = conn.update_api_key(apiKey=apiKey, patchOperations=_api_key_patchops("add", pvlist))
return response
def _api_key_patch_remove(conn, apiKey, pvlist):
"""
the remove patch operation for a list of (path, value) tuples on an ApiKey resource list path
"""
response = conn.update_api_key(
apiKey=apiKey, patchOperations=_api_key_patchops("remove", pvlist)
)
return response
[docs]
def update_api_key_description(
apiKey, description, region=None, key=None, keyid=None, profile=None
):
"""
update the given apiKey with the given description.
apiKey (str):
The ID of the API key to update.
description (str):
The new description for the API key.
region (str, optional):
The AWS region where the REST API is located.
key (str, optional):
The AWS secret access key.
keyid (str, optional):
The AWS access key ID.
profile (str, optional):
The profile to use for AWS credentials.
CLI Example:
.. code-block:: bash
salt myminion boto3_apigateway.update_api_key_description api_key description
"""
try:
conn = _get_conn("apigateway", region=region, key=key, keyid=keyid, profile=profile)
response = _api_key_patch_replace(conn, apiKey, "/description", description)
return {"updated": True, "apiKey": _convert_datetime_str(response)}
except ClientError as e:
return {"updated": False, "error": boto3mod.get_error(e)}
[docs]
def enable_api_key(apiKey, region=None, key=None, keyid=None, profile=None):
"""
enable the given apiKey.
apiKey (str):
The ID of the API key to enable.
region (str, optional):
The AWS region where the REST API is located.
key (str, optional):
The AWS secret access key.
keyid (str, optional):
The AWS access key ID.
profile (str, optional):
The profile to use for AWS credentials.
CLI Example:
.. code-block:: bash
salt myminion boto3_apigateway.enable_api_key api_key region=us-west-2 \
key=mysecretkey keyid=myaccesskeyid profile=myprofile
"""
try:
conn = _get_conn("apigateway", region=region, key=key, keyid=keyid, profile=profile)
response = _api_key_patch_replace(conn, apiKey, "/enabled", "True")
return {"apiKey": _convert_datetime_str(response)}
except ClientError as e:
return {"error": boto3mod.get_error(e)}
[docs]
def disable_api_key(apiKey, region=None, key=None, keyid=None, profile=None):
"""
disable the given apiKey.
apiKey (str):
The ID of the API key to disable.
region (str, optional):
The AWS region where the REST API is located.
key (str, optional):
The AWS secret access key.
keyid (str, optional):
The AWS access key ID.
profile (str, optional):
The profile to use for AWS credentials.
CLI Example:
.. code-block:: bash
salt myminion boto3_apigateway.disable_api_key api_key region=us-west-2 \
key=mysecretkey keyid=myaccesskeyid profile=myprofile
"""
try:
conn = _get_conn("apigateway", region=region, key=key, keyid=keyid, profile=profile)
response = _api_key_patch_replace(conn, apiKey, "/enabled", "False")
return {"apiKey": _convert_datetime_str(response)}
except ClientError as e:
return {"error": boto3mod.get_error(e)}
[docs]
def associate_api_key_stagekeys(
apiKey, stagekeyslist, region=None, key=None, keyid=None, profile=None
):
"""
associate the given stagekeyslist to the given apiKey.
apiKey (str):
The ID of the API key to associate the stage keys with.
stagekeyslist (list):
A list of stage keys to associate with the API key.
region (str, optional):
The AWS region where the REST API is located.
key (str, optional):
The AWS secret access key.
keyid (str, optional):
The AWS access key ID.
profile (str, optional):
The profile to use for AWS credentials.
CLI Example:
.. code-block:: bash
salt myminion boto3_apigateway.associate_stagekeys_api_key \
api_key '["restapi id/stage name", ...]' region=us-west-2 \
key=mysecretkey keyid=myaccesskeyid profile=myprofile
"""
try:
conn = _get_conn("apigateway", region=region, key=key, keyid=keyid, profile=profile)
pvlist = [("/stages", stagekey) for stagekey in stagekeyslist]
response = _api_key_patch_add(conn, apiKey, pvlist)
return {"associated": True, "apiKey": _convert_datetime_str(response)}
except ClientError as e:
return {"associated": False, "error": boto3mod.get_error(e)}
[docs]
def disassociate_api_key_stagekeys(
apiKey, stagekeyslist, region=None, key=None, keyid=None, profile=None
):
"""
disassociate the given stagekeyslist to the given apiKey.
apiKey (str):
The ID of the API key to disassociate the stage keys from.
stagekeyslist (list):
A list of stage keys to disassociate from the API key.
region (str, optional):
The AWS region where the REST API is located.
key (str, optional):
The AWS secret access key.
keyid (str, optional):
The AWS access key ID.
profile (str, optional):
The profile to use for AWS credentials.
CLI Example:
.. code-block:: bash
salt myminion boto3_apigateway.disassociate_stagekeys_api_key \
api_key '["restapi id/stage name", ...]' region=us-west-2 \
key=mysecretkey keyid=myaccesskeyid profile=myprofile
"""
try:
conn = _get_conn("apigateway", region=region, key=key, keyid=keyid, profile=profile)
pvlist = [("/stages", stagekey) for stagekey in stagekeyslist]
_api_key_patch_remove(conn, apiKey, pvlist)
return {"disassociated": True}
except ClientError as e:
return {"disassociated": False, "error": boto3mod.get_error(e)}
[docs]
def describe_api_deployments(restApiId, region=None, key=None, keyid=None, profile=None):
"""
Gets information about the defined API Deployments. Return list of api deployments.
restApiId (str):
The ID of the REST API for which to describe deployments.
region (str, optional):
The AWS region where the REST API is located.
key (str, optional):
The AWS secret access key.
keyid (str, optional):
The AWS access key ID.
profile (str, optional):
The profile to use for AWS credentials.
CLI Example:
.. code-block:: bash
salt myminion boto3_apigateway.describe_api_deployments restApiId
"""
try:
conn = _get_conn("apigateway", region=region, key=key, keyid=keyid, profile=profile)
deployments = []
_deployments = conn.get_deployments(restApiId=restApiId)
while True:
if _deployments:
deployments = deployments + _deployments["items"]
if "position" not in _deployments:
break
_deployments = conn.get_deployments(
restApiId=restApiId, position=_deployments["position"]
)
return {"deployments": [_convert_datetime_str(deployment) for deployment in deployments]}
except ClientError as e:
return {"error": boto3mod.get_error(e)}
[docs]
def describe_api_deployment(
restApiId, deploymentId, region=None, key=None, keyid=None, profile=None
):
"""
Get API deployment for a given restApiId and deploymentId.
restApiId (str):
The ID of the REST API for which to describe the deployment.
deploymentId (str):
The ID of the deployment to describe.
region (str, optional):
The AWS region where the REST API is located.
key (str, optional):
The AWS secret access key.
keyid (str, optional):
The AWS access key ID.
profile (str, optional):
The profile to use for AWS credentials.
CLI Example:
.. code-block:: bash
salt myminion boto3_apigateway.describe_api_deployment restApiId deploymentId
"""
try:
conn = _get_conn("apigateway", region=region, key=key, keyid=keyid, profile=profile)
deployment = conn.get_deployment(restApiId=restApiId, deploymentId=deploymentId)
return {"deployment": _convert_datetime_str(deployment)}
except ClientError as e:
return {"error": boto3mod.get_error(e)}
[docs]
def activate_api_deployment(
restApiId, stageName, deploymentId, region=None, key=None, keyid=None, profile=None
):
"""
Activates previously deployed deployment for a given stage.
restApiId (str):
The ID of the REST API for which to activate the deployment.
stageName (str):
The name of the stage to activate the deployment for.
deploymentId (str):
The ID of the deployment to activate.
region (str, optional):
The AWS region where the REST API is located.
key (str, optional):
The AWS secret access key.
keyid (str, optional):
The AWS access key ID.
profile (str, optional):
The profile to use for AWS credentials.
CLI Example:
.. code-block:: bash
salt myminion boto3_apigateway.activate_api_deployment restApiId stageName deploymentId
"""
try:
conn = _get_conn("apigateway", region=region, key=key, keyid=keyid, profile=profile)
response = conn.update_stage(
restApiId=restApiId,
stageName=stageName,
patchOperations=[{"op": "replace", "path": "/deploymentId", "value": deploymentId}],
)
return {"set": True, "response": _convert_datetime_str(response)}
except ClientError as e:
return {"set": False, "error": boto3mod.get_error(e)}
[docs]
def create_api_deployment(
restApiId,
stageName,
stageDescription="",
description="",
cacheClusterEnabled=False,
cacheClusterSize="0.5",
variables=None,
region=None,
key=None,
keyid=None,
profile=None,
):
"""
Creates a new API deployment.
restApiId (str):
The ID of the REST API for which to create the deployment.
stageName (str):
The name of the stage to create the deployment for.
stageDescription (str, optional):
The description of the stage.
description (str, optional):
The description of the deployment.
cacheClusterEnabled (bool, optional):
Whether the cache cluster is enabled for the stage.
cacheClusterSize (str, optional):
The size of the cache cluster for the stage.
variables (dict, optional):
The stage variables to set for the stage.
region (str, optional):
The AWS region where the REST API is located.
key (str, optional):
The AWS secret access key.
keyid (str, optional):
The AWS access key ID.
profile (str, optional):
The profile to use for AWS credentials.
CLI Example:
.. code-block:: bash
salt myminion boto3_apigateway.create_api_deployment restApiId stageName stageDescription='' \
description='' cacheClusterEnabled=True|False cacheClusterSize=0.5 variables='{"name": "value"}'
"""
try:
variables = {} if variables is None else variables
conn = _get_conn("apigateway", region=region, key=key, keyid=keyid, profile=profile)
deployment = conn.create_deployment(
restApiId=restApiId,
stageName=stageName,
stageDescription=stageDescription,
description=description,
cacheClusterEnabled=cacheClusterEnabled,
cacheClusterSize=cacheClusterSize,
variables=variables,
)
return {"created": True, "deployment": _convert_datetime_str(deployment)}
except ClientError as e:
return {"created": False, "error": boto3mod.get_error(e)}
[docs]
def delete_api_deployment(restApiId, deploymentId, region=None, key=None, keyid=None, profile=None):
"""
Deletes API deployment for a given restApiId and deploymentID
restApiId (str):
The ID of the REST API.
deploymentId (str):
The ID of the deployment to delete.
region (str, optional):
The AWS region where the REST API is located.
key (str, optional):
The AWS secret access key.
keyid (str, optional):
The AWS access key ID.
profile (str, optional):
The profile to use for AWS credentials.
CLI Example:
.. code-block:: bash
salt myminion boto3_apigateway.delete_api_deployment restApiId deploymentId
"""
try:
conn = _get_conn("apigateway", region=region, key=key, keyid=keyid, profile=profile)
conn.delete_deployment(restApiId=restApiId, deploymentId=deploymentId)
return {"deleted": True}
except ClientError as e:
return {"deleted": False, "error": boto3mod.get_error(e)}
[docs]
def overwrite_api_stage_variables(
restApiId, stageName, variables, region=None, key=None, keyid=None, profile=None
):
"""
Overwrite the stage variables for the given restApiId and stage name with the given variables,
variables must be in the form of a dictionary. Overwrite will always remove all the existing
stage variables associated with the given restApiId and stage name, follow by the adding of all the
variables specified in the variables dictionary
restApiId (str):
The ID of the REST API.
stageName (str):
The name of the stage.
variables (dict):
The stage variables to set, in the form of a dictionary.
region (str, optional):
The AWS region where the REST API is located.
key (str, optional):
The AWS secret access key.
keyid (str, optional):
The AWS access key ID.
profile (str, optional):
The profile to use for AWS credentials.
CLI Example:
.. code-block:: bash
salt myminion boto3_apigateway.overwrite_api_stage_variables restApiId stageName variables='{"name": "value"}'
"""
try:
res = describe_api_stage(
restApiId, stageName, region=region, key=key, keyid=keyid, profile=profile
)
if res.get("error"):
return {"overwrite": False, "error": res.get("error")}
conn = _get_conn("apigateway", region=region, key=key, keyid=keyid, profile=profile)
# remove all existing variables that are not in the given variables,
# followed by adding of the variables
stage = res.get("stage")
old_vars = stage.get("variables", {})
patch_ops = []
for old_var in old_vars:
if old_var not in variables:
patch_ops.append({"op": "remove", "path": f"/variables/{old_var}", "value": ""})
for var, val in variables.items():
if var not in old_vars or old_vars[var] != val:
patch_ops.append({"op": "replace", "path": f"/variables/{var}", "value": val})
if patch_ops:
stage = conn.update_stage(
restApiId=restApiId, stageName=stageName, patchOperations=patch_ops
)
return {"overwrite": True, "stage": _convert_datetime_str(stage)}
except ClientError as e:
return {"overwrite": False, "error": boto3mod.get_error(e)}
[docs]
def describe_api_stage(restApiId, stageName, region=None, key=None, keyid=None, profile=None):
"""
Get API stage for a given apiID and stage name
restApiId (str):
The ID of the REST API.
stageName (str):
The name of the stage.
region (str, optional):
The AWS region where the REST API is located.
key (str, optional):
The AWS secret access key.
keyid (str, optional):
The AWS access key ID.
profile (str, optional):
The profile to use for AWS credentials.
CLI Example:
.. code-block:: bash
salt myminion boto3_apigateway.describe_api_stage restApiId stageName
"""
try:
conn = _get_conn("apigateway", region=region, key=key, keyid=keyid, profile=profile)
stage = conn.get_stage(restApiId=restApiId, stageName=stageName)
return {"stage": _convert_datetime_str(stage)}
except ClientError as e:
return {"error": boto3mod.get_error(e)}
[docs]
def describe_api_stages(restApiId, deploymentId, region=None, key=None, keyid=None, profile=None):
"""
Get all API stages for a given apiID and deploymentID
restApiId (str):
The ID of the REST API.
deploymentId (str):
The ID of the deployment.
region (str, optional):
The AWS region where the REST API is located.
key (str, optional):
The AWS secret access key.
keyid (str, optional):
The AWS access key ID.
profile (str, optional):
The profile to use for AWS credentials.
CLI Example:
.. code-block:: bash
salt myminion boto3_apigateway.describe_api_stages restApiId deploymentId
"""
try:
conn = _get_conn("apigateway", region=region, key=key, keyid=keyid, profile=profile)
stages = conn.get_stages(restApiId=restApiId, deploymentId=deploymentId)
return {"stages": [_convert_datetime_str(stage) for stage in stages["item"]]}
except ClientError as e:
return {"error": boto3mod.get_error(e)}
[docs]
def create_api_stage(
restApiId,
stageName,
deploymentId,
description="",
cacheClusterEnabled=False,
cacheClusterSize="0.5",
variables=None,
region=None,
key=None,
keyid=None,
profile=None,
):
"""
Creates a new API stage for a given restApiId and deploymentId.
restApiId (str):
The ID of the REST API.
stageName (str):
The name of the stage.
deploymentId (str):
The ID of the deployment.
description (str, optional):
The description of the stage.
cacheClusterEnabled (bool, optional):
Whether the cache cluster is enabled.
cacheClusterSize (str, optional):
The size of the cache cluster.
variables (dict, optional):
The stage variables.
region (str, optional):
The AWS region where the REST API is located.
key (str, optional):
The AWS secret access key.
keyid (str, optional):
The AWS access key ID.
profile (str, optional):
The profile to use for AWS credentials.
CLI Example:
.. code-block:: bash
salt myminion boto3_apigateway.create_api_stage restApiId stagename deploymentId \
description='' cacheClusterEnabled=True|False cacheClusterSize='0.5' variables='{"name": "value"}'
"""
try:
variables = {} if variables is None else variables
conn = _get_conn("apigateway", region=region, key=key, keyid=keyid, profile=profile)
stage = conn.create_stage(
restApiId=restApiId,
stageName=stageName,
deploymentId=deploymentId,
description=description,
cacheClusterEnabled=cacheClusterEnabled,
cacheClusterSize=cacheClusterSize,
variables=variables,
)
return {"created": True, "stage": _convert_datetime_str(stage)}
except ClientError as e:
return {"created": False, "error": boto3mod.get_error(e)}
[docs]
def delete_api_stage(restApiId, stageName, region=None, key=None, keyid=None, profile=None):
"""
Deletes stage identified by stageName from API identified by restApiId
restApiId (str):
The ID of the REST API.
stageName (str):
The name of the stage.
region (str, optional):
The AWS region where the REST API is located.
key (str, optional):
The AWS secret access key.
keyid (str, optional):
The AWS access key ID.
profile (str, optional):
The profile to use for AWS credentials.
CLI Example:
.. code-block:: bash
salt myminion boto3_apigateway.delete_api_stage restApiId stageName
"""
try:
conn = _get_conn("apigateway", region=region, key=key, keyid=keyid, profile=profile)
conn.delete_stage(restApiId=restApiId, stageName=stageName)
return {"deleted": True}
except ClientError as e:
return {"deleted": False, "error": boto3mod.get_error(e)}
[docs]
def flush_api_stage_cache(restApiId, stageName, region=None, key=None, keyid=None, profile=None):
"""
Flushes cache for the stage identified by stageName from API identified by restApiId
restApiId (str):
The ID of the REST API.
stageName (str):
The name of the stage.
region (str, optional):
The AWS region where the REST API is located.
key (str, optional):
The AWS secret access key.
keyid (str, optional):
The AWS access key ID.
profile (str, optional):
The profile to use for AWS credentials.
CLI Example:
.. code-block:: bash
salt myminion boto3_apigateway.flush_api_stage_cache restApiId stageName
"""
try:
conn = _get_conn("apigateway", region=region, key=key, keyid=keyid, profile=profile)
conn.flush_stage_cache(restApiId=restApiId, stageName=stageName)
return {"flushed": True}
except ClientError as e:
return {"flushed": False, "error": boto3mod.get_error(e)}
[docs]
def create_api_method(
restApiId,
resourcePath,
httpMethod,
authorizationType,
apiKeyRequired=False,
requestParameters=None,
requestModels=None,
region=None,
key=None,
keyid=None,
profile=None,
):
"""
Creates API method for a resource in the given API
restApiId (str):
The ID of the REST API.
resourcePath (str):
The path of the resource.
httpMethod (str):
The HTTP method for the API method.
authorizationType (str):
The authorization type for the API method.
apiKeyRequired (bool, optional):
Whether an API key is required for the method.
requestParameters (dict, optional):
The request parameters for the method.
requestModels (dict, optional):
The request models for the method.
region (str, optional):
The AWS region where the REST API is located.
key (str, optional):
The AWS secret access key.
keyid (str, optional):
The AWS access key ID.
profile (str, optional):
The profile to use for AWS credentials.
CLI Example:
.. code-block:: bash
salt myminion boto3_apigateway.create_api_method restApiId resourcePath, httpMethod, authorizationType, \
apiKeyRequired=False, requestParameters='{"name", "value"}', requestModels='{"content-type", "value"}'
"""
try:
resource = describe_api_resource(
restApiId,
resourcePath,
region=region,
key=key,
keyid=keyid,
profile=profile,
).get("resource")
if resource:
requestParameters = {} if requestParameters is None else requestParameters
requestModels = {} if requestModels is None else requestModels
conn = _get_conn("apigateway", region=region, key=key, keyid=keyid, profile=profile)
method = conn.put_method(
restApiId=restApiId,
resourceId=resource["id"],
httpMethod=httpMethod,
authorizationType=str(authorizationType),
apiKeyRequired=apiKeyRequired,
requestParameters=requestParameters,
requestModels=requestModels,
)
return {"created": True, "method": method}
return {"created": False, "error": "Failed to create method"}
except ClientError as e:
return {"created": False, "error": boto3mod.get_error(e)}
[docs]
def describe_api_method(
restApiId, resourcePath, httpMethod, region=None, key=None, keyid=None, profile=None
):
"""
Get API method for a resource in the given API
restApiId (str):
The ID of the REST API.
resourcePath (str):
The path of the resource.
httpMethod (str):
The HTTP method for the API method.
region (str, optional):
The AWS region where the REST API is located.
key (str, optional):
The AWS secret access key.
keyid (str, optional):
The AWS access key ID.
profile (str, optional):
The profile to use for AWS credentials.
CLI Example:
.. code-block:: bash
salt myminion boto3_apigateway.describe_api_method restApiId resourcePath httpMethod
"""
try:
resource = describe_api_resource(
restApiId,
resourcePath,
region=region,
key=key,
keyid=keyid,
profile=profile,
).get("resource")
if resource:
conn = _get_conn("apigateway", region=region, key=key, keyid=keyid, profile=profile)
method = conn.get_method(
restApiId=restApiId, resourceId=resource["id"], httpMethod=httpMethod
)
return {"method": _convert_datetime_str(method)}
return {"error": "get API method failed: no such resource"}
except ClientError as e:
return {"error": boto3mod.get_error(e)}
[docs]
def delete_api_method(
restApiId, resourcePath, httpMethod, region=None, key=None, keyid=None, profile=None
):
"""
Delete API method for a resource in the given API
restApiId (str):
The ID of the REST API.
resourcePath (str):
The path of the resource.
httpMethod (str):
The HTTP method for the API method.
region (str, optional):
The AWS region where the REST API is located.
key (str, optional):
The AWS secret access key.
keyid (str, optional):
The AWS access key ID.
profile (str, optional):
The profile to use for AWS credentials.
CLI Example:
.. code-block:: bash
salt myminion boto3_apigateway.delete_api_method restApiId resourcePath httpMethod
"""
try:
resource = describe_api_resource(
restApiId,
resourcePath,
region=region,
key=key,
keyid=keyid,
profile=profile,
).get("resource")
if resource:
conn = _get_conn("apigateway", region=region, key=key, keyid=keyid, profile=profile)
conn.delete_method(
restApiId=restApiId, resourceId=resource["id"], httpMethod=httpMethod
)
return {"deleted": True}
return {"deleted": False, "error": "get API method failed: no such resource"}
except ClientError as e:
return {"deleted": False, "error": boto3mod.get_error(e)}
[docs]
def create_api_method_response(
restApiId,
resourcePath,
httpMethod,
statusCode,
responseParameters=None,
responseModels=None,
region=None,
key=None,
keyid=None,
profile=None,
):
"""
Create API method response for a method on a given resource in the given API
restApiId (str):
The ID of the REST API.
resourcePath (str):
The path of the resource.
httpMethod (str):
The HTTP method for the API method.
statusCode (str):
The status code for the method response.
responseParameters (dict, optional):
The response parameters for the method response.
responseModels (dict, optional):
The response models for the method response.
region (str, optional):
The AWS region where the REST API is located.
key (str, optional):
The AWS secret access key.
keyid (str, optional):
The AWS access key ID.
profile (str, optional):
The profile to use for AWS credentials.
CLI Example:
.. code-block:: bash
salt myminion boto3_apigateway.create_api_method_response restApiId resourcePath httpMethod \
statusCode responseParameters='{"name", "True|False"}' responseModels='{"content-type", "model"}'
"""
try:
resource = describe_api_resource(
restApiId,
resourcePath,
region=region,
key=key,
keyid=keyid,
profile=profile,
).get("resource")
if resource:
responseParameters = {} if responseParameters is None else responseParameters
responseModels = {} if responseModels is None else responseModels
conn = _get_conn("apigateway", region=region, key=key, keyid=keyid, profile=profile)
response = conn.put_method_response(
restApiId=restApiId,
resourceId=resource["id"],
httpMethod=httpMethod,
statusCode=str(statusCode),
responseParameters=responseParameters,
responseModels=responseModels,
)
return {"created": True, "response": response}
return {"created": False, "error": "no such resource"}
except ClientError as e:
return {"created": False, "error": boto3mod.get_error(e)}
[docs]
def delete_api_method_response(
restApiId,
resourcePath,
httpMethod,
statusCode,
region=None,
key=None,
keyid=None,
profile=None,
):
"""
Delete API method response for a resource in the given API
restApiId (str):
The ID of the REST API.
resourcePath (str):
The path of the resource.
httpMethod (str):
The HTTP method for the API method.
statusCode (str):
The status code for the method response.
region (str, optional):
The AWS region where the REST API is located.
key (str, optional):
The AWS secret access key.
keyid (str, optional):
The AWS access key ID.
profile (str, optional):
The profile to use for AWS credentials.
CLI Example:
.. code-block:: bash
salt myminion boto3_apigateway.delete_api_method_response restApiId resourcePath httpMethod statusCode
"""
try:
resource = describe_api_resource(
restApiId,
resourcePath,
region=region,
key=key,
keyid=keyid,
profile=profile,
).get("resource")
if resource:
conn = _get_conn("apigateway", region=region, key=key, keyid=keyid, profile=profile)
conn.delete_method_response(
restApiId=restApiId,
resourceId=resource["id"],
httpMethod=httpMethod,
statusCode=str(statusCode),
)
return {"deleted": True}
return {"deleted": False, "error": "no such resource"}
except ClientError as e:
return {"deleted": False, "error": boto3mod.get_error(e)}
[docs]
def describe_api_method_response(
restApiId,
resourcePath,
httpMethod,
statusCode,
region=None,
key=None,
keyid=None,
profile=None,
):
"""
Get API method response for a resource in the given API
restApiId (str):
The ID of the REST API.
resourcePath (str):
The path of the resource.
httpMethod (str):
The HTTP method for the API method.
statusCode (str):
The status code for the method response.
region (str, optional):
The AWS region where the REST API is located.
key (str, optional):
The AWS secret access key.
keyid (str, optional):
The AWS access key ID.
profile (str, optional):
The profile to use for AWS credentials.
CLI Example:
.. code-block:: bash
salt myminion boto3_apigateway.describe_api_method_response restApiId resourcePath httpMethod statusCode
"""
try:
resource = describe_api_resource(
restApiId,
resourcePath,
region=region,
key=key,
keyid=keyid,
profile=profile,
).get("resource")
if resource:
conn = _get_conn("apigateway", region=region, key=key, keyid=keyid, profile=profile)
response = conn.get_method_response(
restApiId=restApiId,
resourceId=resource["id"],
httpMethod=httpMethod,
statusCode=str(statusCode),
)
return {"response": _convert_datetime_str(response)}
return {"error": "no such resource"}
except ClientError as e:
return {"error": boto3mod.get_error(e)}
[docs]
def describe_api_models(restApiId, region=None, key=None, keyid=None, profile=None):
"""
Get all models for a given API
restApiId (str):
The ID of the REST API.
region (str, optional):
The AWS region where the REST API is located.
key (str, optional):
The AWS secret access key.
keyid (str, optional):
The AWS access key ID.
profile (str, optional):
The profile to use for AWS credentials.
CLI Example:
.. code-block:: bash
salt myminion boto3_apigateway.describe_api_models restApiId
"""
try:
conn = _get_conn("apigateway", region=region, key=key, keyid=keyid, profile=profile)
models = _multi_call(conn.get_models, "items", restApiId=restApiId)
return {"models": [_convert_datetime_str(model) for model in models]}
except ClientError as e:
return {"error": boto3mod.get_error(e)}
[docs]
def describe_api_model(
restApiId, modelName, flatten=True, region=None, key=None, keyid=None, profile=None
):
"""
Get a model by name for a given API
restApiId (str):
The ID of the REST API.
modelName (str):
The name of the model to retrieve.
flatten (bool, optional):
Whether to flatten the model structure. Defaults to True.
region (str, optional):
The AWS region where the REST API is located.
key (str, optional):
The AWS secret access key.
keyid (str, optional):
The AWS access key ID.
profile (str, optional):
The profile to use for AWS credentials.
CLI Example:
.. code-block:: bash
salt myminion boto3_apigateway.describe_api_model restApiId modelName [True]
"""
try:
conn = _get_conn("apigateway", region=region, key=key, keyid=keyid, profile=profile)
model = conn.get_model(restApiId=restApiId, modelName=modelName, flatten=flatten)
return {"model": _convert_datetime_str(model)}
except ClientError as e:
return {"error": boto3mod.get_error(e)}
[docs]
def api_model_exists(restApiId, modelName, region=None, key=None, keyid=None, profile=None):
"""
Check to see if the given modelName exists in the given restApiId
restApiId (str):
The ID of the REST API.
modelName (str):
The name of the model to check for existence.
region (str, optional):
The AWS region where the REST API is located.
key (str, optional):
The AWS secret access key.
keyid (str, optional):
The AWS access key ID.
profile (str, optional):
The profile to use for AWS credentials.
CLI Example:
.. code-block:: bash
salt myminion boto3_apigateway.api_model_exists restApiId modelName
"""
r = describe_api_model(
restApiId, modelName, region=region, key=key, keyid=keyid, profile=profile
)
return {"exists": bool(r.get("model"))}
def _api_model_patch_replace(conn, restApiId, modelName, path, value):
"""
the replace patch operation on a Model resource
"""
response = conn.update_model(
restApiId=restApiId,
modelName=modelName,
patchOperations=[{"op": "replace", "path": path, "value": value}],
)
return response
[docs]
def update_api_model_schema(
restApiId, modelName, schema, region=None, key=None, keyid=None, profile=None
):
"""
update the schema (in python dictionary format) for the given model in the given restApiId
restApiId (str):
The ID of the REST API.
modelName (str):
The name of the model to update.
schema (dict or str):
The new schema for the model. Can be a Python dictionary or a JSON string.
region (str, optional):
The AWS region where the REST API is located.
key (str, optional):
The AWS secret access key.
keyid (str, optional):
The AWS access key ID.
profile (str, optional):
The profile to use for AWS credentials.
CLI Example:
.. code-block:: bash
salt myminion boto3_apigateway.update_api_model_schema restApiId modelName schema
"""
try:
schema_json = salt.utils.json.dumps(schema) if isinstance(schema, dict) else schema
conn = _get_conn("apigateway", region=region, key=key, keyid=keyid, profile=profile)
response = _api_model_patch_replace(conn, restApiId, modelName, "/schema", schema_json)
return {"updated": True, "model": _convert_datetime_str(response)}
except ClientError as e:
return {"updated": False, "error": boto3mod.get_error(e)}
[docs]
def delete_api_model(restApiId, modelName, region=None, key=None, keyid=None, profile=None):
"""
Delete a model identified by name in a given API
restApiId (str):
The ID of the REST API.
modelName (str):
The name of the model to delete.
region (str, optional):
The AWS region where the REST API is located.
key (str, optional):
The AWS secret access key.
keyid (str, optional):
The AWS access key ID.
profile (str, optional):
The profile to use for AWS credentials.
CLI Example:
.. code-block:: bash
salt myminion boto3_apigateway.delete_api_model restApiId modelName
"""
try:
conn = _get_conn("apigateway", region=region, key=key, keyid=keyid, profile=profile)
conn.delete_model(restApiId=restApiId, modelName=modelName)
return {"deleted": True}
except ClientError as e:
return {"deleted": False, "error": boto3mod.get_error(e)}
[docs]
def create_api_model(
restApiId,
modelName,
modelDescription,
schema,
contentType="application/json",
region=None,
key=None,
keyid=None,
profile=None,
):
"""
Create a new model in a given API with a given schema, currently only contentType supported is
'application/json'
restApiId (str):
The ID of the REST API.
modelName (str):
The name of the model to create.
modelDescription (str):
A description of the model.
schema (dict or str):
The schema for the model. Can be a Python dictionary or a JSON string.
contentType (str, optional):
The content type for the model schema. Default is 'application/json'.
region (str, optional):
The AWS region where the REST API is located.
key (str, optional):
The AWS secret access key.
keyid (str, optional):
The AWS access key ID.
profile (str, optional):
The profile to use for AWS credentials.
CLI Example:
.. code-block:: bash
salt myminion boto3_apigateway.create_api_model restApiId modelName modelDescription '<schema>' 'content-type'
"""
try:
schema_json = salt.utils.json.dumps(schema) if isinstance(schema, dict) else schema
conn = _get_conn("apigateway", region=region, key=key, keyid=keyid, profile=profile)
model = conn.create_model(
restApiId=restApiId,
name=modelName,
description=modelDescription,
schema=schema_json,
contentType=contentType,
)
return {"created": True, "model": _convert_datetime_str(model)}
except ClientError as e:
return {"created": False, "error": boto3mod.get_error(e)}
[docs]
def describe_api_integration(
restApiId, resourcePath, httpMethod, region=None, key=None, keyid=None, profile=None
):
"""
Get an integration for a given method in a given API
restApiId (str):
The ID of the REST API.
resourcePath (str):
The path of the resource.
httpMethod (str):
The HTTP method of the integration.
region (str, optional):
The AWS region where the REST API is located.
key (str, optional):
The AWS secret access key.
keyid (str, optional):
The AWS access key ID.
profile (str, optional):
The profile to use for AWS credentials.
CLI Example:
.. code-block:: bash
salt myminion boto3_apigateway.describe_api_integration restApiId resourcePath httpMethod
"""
try:
resource = describe_api_resource(
restApiId,
resourcePath,
region=region,
key=key,
keyid=keyid,
profile=profile,
).get("resource")
if resource:
conn = _get_conn("apigateway", region=region, key=key, keyid=keyid, profile=profile)
integration = conn.get_integration(
restApiId=restApiId, resourceId=resource["id"], httpMethod=httpMethod
)
return {"integration": _convert_datetime_str(integration)}
return {"error": "no such resource"}
except ClientError as e:
return {"error": boto3mod.get_error(e)}
[docs]
def describe_api_integration_response(
restApiId,
resourcePath,
httpMethod,
statusCode,
region=None,
key=None,
keyid=None,
profile=None,
):
"""
Get an integration response for a given method in a given API
restApiId (str):
The ID of the REST API.
resourcePath (str):
The path of the resource.
httpMethod (str):
The HTTP method of the integration.
statusCode (str):
The status code of the integration response.
region (str, optional):
The AWS region where the REST API is located.
key (str, optional):
The AWS secret access key.
keyid (str, optional):
The AWS access key ID.
profile (str, optional):
The profile to use for AWS credentials.
CLI Example:
.. code-block:: bash
salt myminion boto3_apigateway.describe_api_integration_response restApiId resourcePath httpMethod statusCode
"""
try:
resource = describe_api_resource(
restApiId,
resourcePath,
region=region,
key=key,
keyid=keyid,
profile=profile,
).get("resource")
if resource:
conn = _get_conn("apigateway", region=region, key=key, keyid=keyid, profile=profile)
response = conn.get_integration_response(
restApiId=restApiId,
resourceId=resource["id"],
httpMethod=httpMethod,
statusCode=statusCode,
)
return {"response": _convert_datetime_str(response)}
return {"error": "no such resource"}
except ClientError as e:
return {"error": boto3mod.get_error(e)}
[docs]
def delete_api_integration(
restApiId, resourcePath, httpMethod, region=None, key=None, keyid=None, profile=None
):
"""
Deletes an integration for a given method in a given API
restApiId (str):
The ID of the REST API.
resourcePath (str):
The path of the resource.
httpMethod (str):
The HTTP method of the integration.
region (str, optional):
The AWS region where the REST API is located.
key (str, optional):
The AWS secret access key.
keyid (str, optional):
The AWS access key ID.
profile (str, optional):
The profile to use for AWS credentials.
CLI Example:
.. code-block:: bash
salt myminion boto3_apigateway.delete_api_integration restApiId resourcePath httpMethod
"""
try:
resource = describe_api_resource(
restApiId,
resourcePath,
region=region,
key=key,
keyid=keyid,
profile=profile,
).get("resource")
if resource:
conn = _get_conn("apigateway", region=region, key=key, keyid=keyid, profile=profile)
conn.delete_integration(
restApiId=restApiId, resourceId=resource["id"], httpMethod=httpMethod
)
return {"deleted": True}
return {"deleted": False, "error": "no such resource"}
except ClientError as e:
return {"deleted": False, "error": boto3mod.get_error(e)}
[docs]
def delete_api_integration_response(
restApiId,
resourcePath,
httpMethod,
statusCode,
region=None,
key=None,
keyid=None,
profile=None,
):
"""
Deletes an integration response for a given method in a given API
restApiId (str):
The ID of the REST API.
resourcePath (str):
The path of the resource.
httpMethod (str):
The HTTP method of the integration.
statusCode (str):
The status code of the integration response.
region (str, optional):
The AWS region where the REST API is located.
key (str, optional):
The AWS secret access key.
keyid (str, optional):
The AWS access key ID.
profile (str, optional):
The profile to use for AWS credentials.
CLI Example:
.. code-block:: bash
salt myminion boto3_apigateway.delete_api_integration_response restApiId resourcePath httpMethod statusCode
"""
try:
resource = describe_api_resource(
restApiId,
resourcePath,
region=region,
key=key,
keyid=keyid,
profile=profile,
).get("resource")
if resource:
conn = _get_conn("apigateway", region=region, key=key, keyid=keyid, profile=profile)
conn.delete_integration_response(
restApiId=restApiId,
resourceId=resource["id"],
httpMethod=httpMethod,
statusCode=statusCode,
)
return {"deleted": True}
return {"deleted": False, "error": "no such resource"}
except ClientError as e:
return {"deleted": False, "error": boto3mod.get_error(e)}
def _get_role_arn(name, region=None, key=None, keyid=None, profile=None):
"""
Helper function to get an ARN if name does not look like an ARN.
"""
if name.startswith("arn:aws:iam:"):
return name
account_id = __salt__["boto3_iam.get_account_id"](
region=region, key=key, keyid=keyid, profile=profile
)
return f"arn:aws:iam::{account_id}:role/{name}"
[docs]
def create_api_integration(
restApiId,
resourcePath,
httpMethod,
integrationType,
integrationHttpMethod,
uri,
credentials,
requestParameters=None,
requestTemplates=None,
region=None,
key=None,
keyid=None,
profile=None,
):
"""
Creates an integration for a given method in a given API.
If integrationType is MOCK, uri and credential parameters will be ignored.
uri is in the form of (substitute APIGATEWAY_REGION and LAMBDA_FUNC_ARN)
"arn:aws:apigateway:APIGATEWAY_REGION:lambda:path/2015-03-31/functions/LAMBDA_FUNC_ARN/invocations"
credentials is in the form of an iam role name or role arn.
restApiId (str):
The ID of the REST API.
resourcePath (str):
The path of the resource.
httpMethod (str):
The HTTP method of the integration.
integrationType (str):
The type of the integration (e.g., MOCK, AWS, HTTP, HTTP_PROXY, AWS_PROXY).
integrationHttpMethod (str):
The HTTP method used for the integration request.
uri (str):
The URI of the integration endpoint.
credentials (str):
The IAM role name or ARN used for the integration.
requestParameters (dict, optional):
The request parameters for the integration.
requestTemplates (dict, optional):
The request templates for the integration.
region (str, optional):
The AWS region where the REST API is located.
key (str, optional):
The AWS secret access key.
keyid (str, optional):
The AWS access key ID.
profile (str, optional):
The profile to use for AWS credentials.
CLI Example:
.. code-block:: bash
salt myminion boto3_apigateway.create_api_integration restApiId resourcePath httpMethod \
integrationType integrationHttpMethod uri credentials ['{}' ['{}']]
"""
try:
credentials = _get_role_arn(
credentials, region=region, key=key, keyid=keyid, profile=profile
)
resource = describe_api_resource(
restApiId,
resourcePath,
region=region,
key=key,
keyid=keyid,
profile=profile,
).get("resource")
if resource:
requestParameters = {} if requestParameters is None else requestParameters
requestTemplates = {} if requestTemplates is None else requestTemplates
conn = _get_conn("apigateway", region=region, key=key, keyid=keyid, profile=profile)
if httpMethod.lower() == "options":
uri = ""
credentials = ""
integration = conn.put_integration(
restApiId=restApiId,
resourceId=resource["id"],
httpMethod=httpMethod,
type=integrationType,
integrationHttpMethod=integrationHttpMethod,
uri=uri,
credentials=credentials,
requestParameters=requestParameters,
requestTemplates=requestTemplates,
)
return {"created": True, "integration": integration}
return {"created": False, "error": "no such resource"}
except ClientError as e:
return {"created": False, "error": boto3mod.get_error(e)}
[docs]
def create_api_integration_response(
restApiId,
resourcePath,
httpMethod,
statusCode,
selectionPattern,
responseParameters=None,
responseTemplates=None,
region=None,
key=None,
keyid=None,
profile=None,
):
"""
Creates an integration response for a given method in a given API
restApiId (str):
The ID of the REST API.
resourcePath (str):
The path of the resource.
httpMethod (str):
The HTTP method of the integration.
statusCode (str):
The status code of the integration response.
selectionPattern (str):
The selection pattern for the integration response.
responseParameters (dict, optional):
The response parameters for the integration response.
responseTemplates (dict, optional):
The response templates for the integration response.
region (str, optional):
The AWS region where the REST API is located.
key (str, optional):
The AWS secret access key.
keyid (str, optional):
The AWS access key ID.
profile (str, optional):
The profile to use for AWS credentials.
CLI Example:
.. code-block:: bash
salt myminion boto3_apigateway.create_api_integration_response restApiId resourcePath httpMethod \
statusCode selectionPattern ['{}' ['{}']]
"""
try:
resource = describe_api_resource(
restApiId,
resourcePath,
region=region,
key=key,
keyid=keyid,
profile=profile,
).get("resource")
if resource:
responseParameters = {} if responseParameters is None else responseParameters
responseTemplates = {} if responseTemplates is None else responseTemplates
conn = _get_conn("apigateway", region=region, key=key, keyid=keyid, profile=profile)
response = conn.put_integration_response(
restApiId=restApiId,
resourceId=resource["id"],
httpMethod=httpMethod,
statusCode=statusCode,
selectionPattern=selectionPattern,
responseParameters=responseParameters,
responseTemplates=responseTemplates,
)
return {"created": True, "response": response}
return {"created": False, "error": "no such resource"}
except ClientError as e:
return {"created": False, "error": boto3mod.get_error(e)}
def _filter_plans(attr, name, plans):
"""
Helper to return list of usage plan items matching the given attribute value.
"""
return [plan for plan in plans if plan[attr] == name]
[docs]
def describe_usage_plans(name=None, plan_id=None, region=None, key=None, keyid=None, profile=None):
"""
Returns a list of existing usage plans, optionally filtered to match a given plan name
name (str, optional):
The name of the usage plan to filter by.
plan_id (str, optional):
The ID of the usage plan to filter by.
region (str, optional):
The AWS region where the usage plans are located.
key (str, optional):
The AWS secret access key.
keyid (str, optional):
The AWS access key ID.
profile (str, optional):
The profile to use for AWS credentials.
CLI Example:
.. code-block:: bash
salt myminion boto3_apigateway.describe_usage_plans
salt myminion boto3_apigateway.describe_usage_plans name='usage plan name'
salt myminion boto3_apigateway.describe_usage_plans plan_id='usage plan id'
"""
try:
conn = _get_conn("apigateway", region=region, key=key, keyid=keyid, profile=profile)
plans = _multi_call(conn.get_usage_plans, "items")
if name:
plans = _filter_plans("name", name, plans)
if plan_id:
plans = _filter_plans("id", plan_id, plans)
return {"plans": [_convert_datetime_str(plan) for plan in plans]}
except ClientError as e:
return {"error": boto3mod.get_error(e)}
def _validate_throttle(throttle):
"""
Helper to verify that throttling parameters are valid
"""
if throttle is not None:
if not isinstance(throttle, dict):
raise TypeError(f"throttle must be a dictionary, provided value: {throttle}")
def _validate_quota(quota):
"""
Helper to verify that quota parameters are valid
"""
if quota is not None:
if not isinstance(quota, dict):
raise TypeError(f"quota must be a dictionary, provided value: {quota}")
periods = ["DAY", "WEEK", "MONTH"]
if "period" not in quota or quota["period"] not in periods:
raise ValueError(
"quota must have a valid period specified, valid values are {}".format(
",".join(periods)
)
)
if "limit" not in quota:
raise ValueError("quota limit must have a valid value")
[docs]
def create_usage_plan(
name,
description=None,
throttle=None,
quota=None,
region=None,
key=None,
keyid=None,
profile=None,
):
"""
Creates a new usage plan with throttling and quotas optionally applied
name (str):
Name of the usage plan
throttle (dict, optional):
A dictionary consisting of the following keys:
rateLimit
requests per second at steady rate, float
burstLimit
maximum number of requests per second, integer
quota (dict, optional):
A dictionary consisting of the following keys:
limit
number of allowed requests per specified quota period [required if quota parameter is present]
offset
number of requests to be subtracted from limit at the beginning of the period [optional]
region (str, optional):
The AWS region where the usage plan is located.
key (str, optional):
The AWS secret access key.
keyid (str, optional):
The AWS access key ID.
profile (str, optional):
The profile to use for AWS credentials.]
CLI Example:
.. code-block:: bash
salt myminion boto3_apigateway.create_usage_plan name='usage plan name' throttle='{"rateLimit": 10.0, "burstLimit": 10}'
"""
try:
_validate_throttle(throttle)
_validate_quota(quota)
values = {"name": name}
if description:
values["description"] = description
if throttle:
values["throttle"] = throttle
if quota:
values["quota"] = quota
conn = _get_conn("apigateway", region=region, key=key, keyid=keyid, profile=profile)
res = conn.create_usage_plan(**values)
return {"created": True, "result": res}
except ClientError as e:
return {"error": boto3mod.get_error(e)}
except (TypeError, ValueError) as e:
return {"error": str(e)}
[docs]
def update_usage_plan(
plan_id, throttle=None, quota=None, region=None, key=None, keyid=None, profile=None
):
"""
Updates an existing usage plan with throttling and quotas
plan_id (str):
Id of the created usage plan
throttle (dict, optional):
A dictionary consisting of the following keys:
rateLimit
requests per second at steady rate, float
burstLimit
maximum number of requests per second, integer
quota
A dictionary consisting of the following keys:
limit
number of allowed requests per specified quota period [required if quota parameter is present]
offset
number of requests to be subtracted from limit at the beginning of the period [optional]
period
quota period, must be one of DAY, WEEK, or MONTH. [required if quota parameter is present
CLI Example:
.. code-block:: bash
salt myminion boto3_apigateway.update_usage_plan plan_id='usage plan id' throttle='{"rateLimit": 10.0, "burstLimit": 10}'
"""
try:
_validate_throttle(throttle)
_validate_quota(quota)
conn = _get_conn("apigateway", region=region, key=key, keyid=keyid, profile=profile)
patchOperations = []
if throttle is None:
patchOperations.append({"op": "remove", "path": "/throttle"})
else:
if "rateLimit" in throttle:
patchOperations.append(
{
"op": "replace",
"path": "/throttle/rateLimit",
"value": str(throttle["rateLimit"]),
}
)
if "burstLimit" in throttle:
patchOperations.append(
{
"op": "replace",
"path": "/throttle/burstLimit",
"value": str(throttle["burstLimit"]),
}
)
if quota is None:
patchOperations.append({"op": "remove", "path": "/quota"})
else:
patchOperations.append(
{
"op": "replace",
"path": "/quota/period",
"value": str(quota["period"]),
}
)
patchOperations.append(
{"op": "replace", "path": "/quota/limit", "value": str(quota["limit"])}
)
if "offset" in quota:
patchOperations.append(
{
"op": "replace",
"path": "/quota/offset",
"value": str(quota["offset"]),
}
)
if patchOperations:
res = conn.update_usage_plan(usagePlanId=plan_id, patchOperations=patchOperations)
return {"updated": True, "result": res}
return {"updated": False}
except ClientError as e:
return {"error": boto3mod.get_error(e)}
except (TypeError, ValueError) as e:
return {"error": str(e)}
[docs]
def delete_usage_plan(plan_id, region=None, key=None, keyid=None, profile=None):
"""
Deletes usage plan identified by plan_id
plan_id (str):
The ID of the usage plan to delete.
region (str, optional):
The AWS region where the usage plan is located.
key (str, optional):
The AWS secret access key.
keyid (str, optional):
The AWS access key ID.
profile (str, optional):
The profile to use for AWS credentials.
CLI Example:
.. code-block:: bash
salt myminion boto3_apigateway.delete_usage_plan plan_id='usage plan id'
"""
try:
existing = describe_usage_plans(
plan_id=plan_id, region=region, key=key, keyid=keyid, profile=profile
)
# don't attempt to delete the usage plan if it does not exist
if "error" in existing:
return {"error": existing["error"]}
if "plans" in existing and existing["plans"]:
conn = _get_conn("apigateway", region=region, key=key, keyid=keyid, profile=profile)
conn.delete_usage_plan(usagePlanId=plan_id)
return {"deleted": True, "usagePlanId": plan_id}
except ClientError as e:
return {"error": boto3mod.get_error(e)}
def _update_usage_plan_apis(plan_id, apis, op, region=None, key=None, keyid=None, profile=None):
"""
Helper function that updates the usage plan identified by plan_id by adding or removing
it to each of the stages, specified by apis parameter.
plan_id (str):
The ID of the usage plan to update.
apis (list):
A list of dictionaries, where each dictionary contains the following:
apiId (str):
A string, which is the id of the created API in AWS ApiGateway
stage (str):
A string, which is the stage that the created API is deployed to.
op (str):
A string that specifies the operation to perform. It can be either 'add' or 'remove'.
region (str, optional):
The AWS region where the usage plan is located.
key (str, optional):
The AWS secret access key.
keyid (str, optional):
The AWS access key ID.
profile (str, optional):
The profile to use for AWS credentials.
"""
try:
patchOperations = []
for api in apis:
patchOperations.append(
{
"op": op,
"path": "/apiStages",
"value": "{}:{}".format(api["apiId"], api["stage"]),
}
)
res = None
if patchOperations:
conn = _get_conn("apigateway", region=region, key=key, keyid=keyid, profile=profile)
res = conn.update_usage_plan(usagePlanId=plan_id, patchOperations=patchOperations)
return {"success": True, "result": res}
except ClientError as e:
return {"error": boto3mod.get_error(e)}
except Exception as e: # pylint: disable=broad-except
return {"error": str(e)}
[docs]
def attach_usage_plan_to_apis(plan_id, apis, region=None, key=None, keyid=None, profile=None):
"""
Attaches given usage plan to each of the apis provided in a list of apiId and stage values
plan_id (str):
The ID of the usage plan to attach the APIs to.
apis (list):
A list of dictionaries, where each dictionary contains the following:
apiId (str):
A string, which is the id of the created API in AWS ApiGateway
stage (str):
A string, which is the stage that the created API is deployed to.
region (str, optional):
The AWS region where the usage plan is located.
key (str, optional):
The AWS secret access key.
keyid (str, optional):
The AWS access key ID.
profile (str, optional):
The profile to use for AWS credentials.
CLI Example:
.. code-block:: bash
salt myminion boto3_apigateway.attach_usage_plan_to_apis plan_id='usage plan id' \
apis='[{"apiId": "some id 1", "stage": "some stage 1"}]'
"""
return _update_usage_plan_apis(
plan_id, apis, "add", region=region, key=key, keyid=keyid, profile=profile
)
[docs]
def detach_usage_plan_from_apis(plan_id, apis, region=None, key=None, keyid=None, profile=None):
"""
Detaches given usage plan from each of the apis provided in a list of apiId and stage values
plan_id (str):
The ID of the usage plan to detach the APIs from.
apis (list):
A list of dictionaries, where each dictionary contains the following:
apiId (str):
A string, which is the id of the created API in AWS ApiGateway
stage (str):
A string, which is the stage that the created API is deployed to.
region (str, optional):
The AWS region where the usage plan is located.
key (str, optional):
The AWS secret access key.
keyid (str, optional):
The AWS access key ID.
profile (str, optional):
The profile to use for AWS credentials.
CLI Example:
.. code-block:: bash
salt myminion boto3_apigateway.detach_usage_plan_to_apis plan_id='usage plan id' \
apis='[{"apiId": "some id 1", "stage": "some stage 1"}]'
"""
return _update_usage_plan_apis(
plan_id, apis, "remove", region=region, key=key, keyid=keyid, profile=profile
)