# aws-apigateway-iot module
<!--BEGIN STABILITY BANNER-->---
> All classes are under active development and subject to non-backward compatible changes or removal in any
> future version. These are not subject to the [Semantic Versioning](https://semver.org/) model.
> This means that while you may use them, you may need to update your source code when upgrading to a newer version of this package.
---
<!--END STABILITY BANNER-->
| **Reference Documentation**:| <span style="font-weight: normal">https://docs.aws.amazon.com/solutions/latest/constructs/</span>|
|:-------------|:-------------|
<div style="height:8px"></div>
| **Language** | **Package** |
|:-------------|-----------------|
| Python|`aws_solutions_constructs.aws_apigateway_iot`|
| Typescript|`@aws-solutions-constructs/aws-apigateway-iot`|
| Java|`software.amazon.awsconstructs.services.apigatewayiot`|
## Overview
This AWS Solutions Construct implements an Amazon API Gateway REST API connected to AWS IoT pattern.
This construct creates a scalable HTTPS proxy between API Gateway and AWS IoT. This comes in handy when wanting to allow legacy devices that do not support the MQTT or MQTT/Websocket protocol to interact with the AWS IoT platform.
This implementation enables write-only messages to be published on given MQTT topics, and also supports shadow updates of HTTPS devices to allowed things in the device registry. It does not involve Lambda functions for proxying messages, and instead relies on direct API Gateway to AWS IoT integration which supports both JSON messages as well as binary messages.
Here is a minimal deployable pattern definition, note that the ATS endpoint for IoT must be used to avoid SSL certificate issues:
Typescript
```python
import { Construct } from 'constructs';
import { Stack, StackProps } from 'aws-cdk-lib';
import { ApiGatewayToIot } from '@aws-solutions-constructs/aws-apigateway-iot';
new ApiGatewayToIot(this, 'ApiGatewayToIotPattern', {
iotEndpoint: 'a1234567890123-ats'
});
```
Python
```python
from aws_solutions_constructs.aws_apigateway_iot import ApiGatewayToIot
from aws_cdk import Stack
from constructs import Construct
ApiGatewayToIot(self, 'ApiGatewayToIotPattern',
iot_endpoint='a1234567890123-ats'
)
```
Java
```java
import software.constructs.Construct;
import software.amazon.awscdk.Stack;
import software.amazon.awscdk.StackProps;
import software.amazon.awsconstructs.services.apigatewayiot.*;
new ApiGatewayToIot(this, "ApiGatewayToIotPattern", new ApiGatewayToIotProps.Builder()
.iotEndpoint("a1234567890123-ats")
.build());
```
## Pattern Construct Props
| **Name** | **Type** | **Description** |
|:-------------|:----------------|-----------------|
|iotEndpoint|`string`|The AWS IoT endpoint subdomain to integrate the API Gateway with (e.g a1234567890123-ats). Note that this must point to the ATS endpoint to avoid SSL certificate trust issues. The endpoint can be retrieved by running `aws iot describe-endpoint --endpoint-type iot:Data-ATS`.|
|apiGatewayCreateApiKey?|`boolean`|If set to `true`, an API Key is created and associated to a UsagePlan. User should specify `x-api-key` header while accessing RestApi. Default value set to `false`|
|apiGatewayExecutionRole?|[`iam.Role`](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_iam.Role.html)|IAM Role used by the API Gateway to access AWS IoT. If not specified, a default role is created with wildcard ('*') access to all topics and things.|
|apiGatewayProps?|[`api.restApiProps`](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_apigateway.RestApiProps.html)|Optional user-provided props to override the default props for the API Gateway.|
|logGroupProps?|[`logs.LogGroupProps`](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_logs.LogGroupProps.html)|User provided props to override the default props for for the CloudWatchLogs LogGroup.|
## Pattern Properties
| **Name** | **Type** | **Description** |
|:-------------|:----------------|-----------------|
|apiGateway|[`api.RestApi`](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_apigateway.RestApi.html)|Returns an instance of the API Gateway REST API created by the pattern.|
|apiGatewayRole|[`iam.Role`](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_iam.Role.html)|Returns an instance of the iam.Role created by the construct for API Gateway.|
|apiGatewayCloudWatchRole?|[`iam.Role`](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_iam.Role.html)|Returns an instance of the iam.Role created by the construct for API Gateway for CloudWatch access.|
|apiGatewayLogGroup|[`logs.LogGroup`](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_logs.LogGroup.html)|Returns an instance of the LogGroup created by the construct for API Gateway access logging to CloudWatch.|
## Default settings
Out of the box implementation of the Construct without any override will set the following defaults:
### Amazon API Gateway
* Deploy an edge-optimized API Endpoint
* Creates API Resources with `POST` Method to publish messages to IoT Topics
* Creates API Resources with `POST` Method to publish messages to ThingShadow & NamedShadows
* Enable CloudWatch logging for API Gateway
* Configure IAM role for API Gateway with access to all topics and things
* Set the default authorizationType for all API methods to IAM
* Enable X-Ray Tracing
* Creates a UsagePlan and associates to `prod` stage
Below is a description of the different resources and methods exposed by the API Gateway after deploying the Construct. See the [Examples](#examples) section for more information on how to easily test these endpoints using `curl`.
|Method | Resource | Query parameter(s) | Return code(s) | Description|
|-------------- | --------------------- | ------------------ | ----------------- | -----------------|
| **POST** | `/message/<topics>` | **qos** | `200/403/500` | By calling this endpoint, you need to pass the topics on which you would like to publish (e.g `/message/device/foo`).|
| **POST** | `/shadow/<thingName>` | **None** | `200/403/500` | This route allows to update the shadow document of a thing, given its `thingName` using Unnamed (classic) shadow type. The body shall comply with the standard shadow structure comprising a `state` node and associated `desired` and `reported` nodes. See the [Updating device shadows](#updating-device-shadows) section for an example.|
| **POST** | `/shadow/<thingName>/<shadowName>` | **None** | `200/403/500` | This route allows to update the named shadow document of a thing, given its `thingName` and the `shadowName` using the Named shadow type. The body shall comply with the standard shadow structure comprising a `state` node and associated `desired` and `reported` nodes. See the [Updating named shadows](#updating-named-shadows) section for an example.|
## Architecture
---
© Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
Raw data
{
"_id": null,
"home_page": "https://github.com/awslabs/aws-solutions-constructs.git",
"name": "aws-solutions-constructs.aws-apigateway-iot",
"maintainer": null,
"docs_url": null,
"requires_python": "~=3.8",
"maintainer_email": null,
"keywords": null,
"author": "Amazon Web Services",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/ec/6c/38b6760d121b49c462419a0926602a0066135fcb8b082a1242c827a7be0e/aws_solutions_constructs_aws_apigateway_iot-2.74.0.tar.gz",
"platform": null,
"description": "# aws-apigateway-iot module\n\n<!--BEGIN STABILITY BANNER-->---\n\n\n\n\n> All classes are under active development and subject to non-backward compatible changes or removal in any\n> future version. These are not subject to the [Semantic Versioning](https://semver.org/) model.\n> This means that while you may use them, you may need to update your source code when upgrading to a newer version of this package.\n\n---\n<!--END STABILITY BANNER-->\n\n| **Reference Documentation**:| <span style=\"font-weight: normal\">https://docs.aws.amazon.com/solutions/latest/constructs/</span>|\n|:-------------|:-------------|\n\n<div style=\"height:8px\"></div>\n\n| **Language** | **Package** |\n|:-------------|-----------------|\n| Python|`aws_solutions_constructs.aws_apigateway_iot`|\n| Typescript|`@aws-solutions-constructs/aws-apigateway-iot`|\n| Java|`software.amazon.awsconstructs.services.apigatewayiot`|\n\n## Overview\n\nThis AWS Solutions Construct implements an Amazon API Gateway REST API connected to AWS IoT pattern.\n\nThis construct creates a scalable HTTPS proxy between API Gateway and AWS IoT. This comes in handy when wanting to allow legacy devices that do not support the MQTT or MQTT/Websocket protocol to interact with the AWS IoT platform.\n\nThis implementation enables write-only messages to be published on given MQTT topics, and also supports shadow updates of HTTPS devices to allowed things in the device registry. It does not involve Lambda functions for proxying messages, and instead relies on direct API Gateway to AWS IoT integration which supports both JSON messages as well as binary messages.\n\nHere is a minimal deployable pattern definition, note that the ATS endpoint for IoT must be used to avoid SSL certificate issues:\n\nTypescript\n\n```python\nimport { Construct } from 'constructs';\nimport { Stack, StackProps } from 'aws-cdk-lib';\nimport { ApiGatewayToIot } from '@aws-solutions-constructs/aws-apigateway-iot';\n\nnew ApiGatewayToIot(this, 'ApiGatewayToIotPattern', {\n iotEndpoint: 'a1234567890123-ats'\n});\n```\n\nPython\n\n```python\nfrom aws_solutions_constructs.aws_apigateway_iot import ApiGatewayToIot\nfrom aws_cdk import Stack\nfrom constructs import Construct\n\nApiGatewayToIot(self, 'ApiGatewayToIotPattern',\n iot_endpoint='a1234567890123-ats'\n)\n```\n\nJava\n\n```java\nimport software.constructs.Construct;\n\nimport software.amazon.awscdk.Stack;\nimport software.amazon.awscdk.StackProps;\nimport software.amazon.awsconstructs.services.apigatewayiot.*;\n\nnew ApiGatewayToIot(this, \"ApiGatewayToIotPattern\", new ApiGatewayToIotProps.Builder()\n .iotEndpoint(\"a1234567890123-ats\")\n .build());\n```\n\n## Pattern Construct Props\n\n| **Name** | **Type** | **Description** |\n|:-------------|:----------------|-----------------|\n|iotEndpoint|`string`|The AWS IoT endpoint subdomain to integrate the API Gateway with (e.g a1234567890123-ats). Note that this must point to the ATS endpoint to avoid SSL certificate trust issues. The endpoint can be retrieved by running `aws iot describe-endpoint --endpoint-type iot:Data-ATS`.|\n|apiGatewayCreateApiKey?|`boolean`|If set to `true`, an API Key is created and associated to a UsagePlan. User should specify `x-api-key` header while accessing RestApi. Default value set to `false`|\n|apiGatewayExecutionRole?|[`iam.Role`](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_iam.Role.html)|IAM Role used by the API Gateway to access AWS IoT. If not specified, a default role is created with wildcard ('*') access to all topics and things.|\n|apiGatewayProps?|[`api.restApiProps`](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_apigateway.RestApiProps.html)|Optional user-provided props to override the default props for the API Gateway.|\n|logGroupProps?|[`logs.LogGroupProps`](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_logs.LogGroupProps.html)|User provided props to override the default props for for the CloudWatchLogs LogGroup.|\n\n## Pattern Properties\n\n| **Name** | **Type** | **Description** |\n|:-------------|:----------------|-----------------|\n|apiGateway|[`api.RestApi`](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_apigateway.RestApi.html)|Returns an instance of the API Gateway REST API created by the pattern.|\n|apiGatewayRole|[`iam.Role`](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_iam.Role.html)|Returns an instance of the iam.Role created by the construct for API Gateway.|\n|apiGatewayCloudWatchRole?|[`iam.Role`](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_iam.Role.html)|Returns an instance of the iam.Role created by the construct for API Gateway for CloudWatch access.|\n|apiGatewayLogGroup|[`logs.LogGroup`](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_logs.LogGroup.html)|Returns an instance of the LogGroup created by the construct for API Gateway access logging to CloudWatch.|\n\n## Default settings\n\nOut of the box implementation of the Construct without any override will set the following defaults:\n\n### Amazon API Gateway\n\n* Deploy an edge-optimized API Endpoint\n* Creates API Resources with `POST` Method to publish messages to IoT Topics\n* Creates API Resources with `POST` Method to publish messages to ThingShadow & NamedShadows\n* Enable CloudWatch logging for API Gateway\n* Configure IAM role for API Gateway with access to all topics and things\n* Set the default authorizationType for all API methods to IAM\n* Enable X-Ray Tracing\n* Creates a UsagePlan and associates to `prod` stage\n\nBelow is a description of the different resources and methods exposed by the API Gateway after deploying the Construct. See the [Examples](#examples) section for more information on how to easily test these endpoints using `curl`.\n\n|Method | Resource | Query parameter(s) | Return code(s) | Description|\n|-------------- | --------------------- | ------------------ | ----------------- | -----------------|\n| **POST** | `/message/<topics>` | **qos** | `200/403/500` | By calling this endpoint, you need to pass the topics on which you would like to publish (e.g `/message/device/foo`).|\n| **POST** | `/shadow/<thingName>` | **None** | `200/403/500` | This route allows to update the shadow document of a thing, given its `thingName` using Unnamed (classic) shadow type. The body shall comply with the standard shadow structure comprising a `state` node and associated `desired` and `reported` nodes. See the [Updating device shadows](#updating-device-shadows) section for an example.|\n| **POST** | `/shadow/<thingName>/<shadowName>` | **None** | `200/403/500` | This route allows to update the named shadow document of a thing, given its `thingName` and the `shadowName` using the Named shadow type. The body shall comply with the standard shadow structure comprising a `state` node and associated `desired` and `reported` nodes. See the [Updating named shadows](#updating-named-shadows) section for an example.|\n\n## Architecture\n\n\n\n---\n\n\n\u00a9 Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "CDK constructs to proxy communication to IotCore using a APIGateway(REST).",
"version": "2.74.0",
"project_urls": {
"Homepage": "https://github.com/awslabs/aws-solutions-constructs.git",
"Source": "https://github.com/awslabs/aws-solutions-constructs.git"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "d16762cf1fd0dae38a52c285728b1ade54bd0b104c2309e903c7b5bcc89bf02a",
"md5": "bf75aaf3e3bc8b7fc8387883f840b787",
"sha256": "56da27addbc216168d8264c3125068c2d0b675fc0f6ebb44603969f224946033"
},
"downloads": -1,
"filename": "aws_solutions_constructs.aws_apigateway_iot-2.74.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "bf75aaf3e3bc8b7fc8387883f840b787",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "~=3.8",
"size": 147145,
"upload_time": "2024-10-22T18:07:09",
"upload_time_iso_8601": "2024-10-22T18:07:09.422841Z",
"url": "https://files.pythonhosted.org/packages/d1/67/62cf1fd0dae38a52c285728b1ade54bd0b104c2309e903c7b5bcc89bf02a/aws_solutions_constructs.aws_apigateway_iot-2.74.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "ec6c38b6760d121b49c462419a0926602a0066135fcb8b082a1242c827a7be0e",
"md5": "edd5a662f87b7635ab36a8037d4e5955",
"sha256": "a12bb28b1a5c66cff07ef954012dcec76836c84d78922ed228dcd217d30d8225"
},
"downloads": -1,
"filename": "aws_solutions_constructs_aws_apigateway_iot-2.74.0.tar.gz",
"has_sig": false,
"md5_digest": "edd5a662f87b7635ab36a8037d4e5955",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "~=3.8",
"size": 148497,
"upload_time": "2024-10-22T18:09:03",
"upload_time_iso_8601": "2024-10-22T18:09:03.686493Z",
"url": "https://files.pythonhosted.org/packages/ec/6c/38b6760d121b49c462419a0926602a0066135fcb8b082a1242c827a7be0e/aws_solutions_constructs_aws_apigateway_iot-2.74.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-22 18:09:03",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "awslabs",
"github_project": "aws-solutions-constructs",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "aws-solutions-constructs.aws-apigateway-iot"
}
JSON
