npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2021 – Pkg Stats / Ryan Hefner

@aws-solutions-constructs/aws-apigateway-iot

v2.0.0-rc.1

Published

CDK constructs to proxy communication to IotCore using a APIGateway(REST).

Downloads

564

Readme

aws-apigateway-iot module


Stability: Experimental

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 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.


| Reference Documentation:| https://docs.aws.amazon.com/solutions/latest/constructs/| |:-------------|:-------------|

| Language | Package | |:-------------|-----------------| |Python Logo Python|aws_solutions_constructs.aws_apigateway_iot| |Typescript Logo Typescript|@aws-solutions-constructs/aws-apigateway-iot| |Java Logo 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 in Typescript:

import { ApiGatewayToIot } from '@aws-solutions-constructs/aws-apigateway-iot';

new ApiGatewayToIot(this, 'ApiGatewayToIotPattern', {
    iotEndpoint: 'a1234567890123-ats'
});

Initializer

new ApiGatewayToIot(scope: Construct, id: string, props: ApiGatewayToIotProps);

Parameters

Pattern Construct Props

| Name | Type | Description | |:-------------|:----------------|-----------------| |iotEndpoint|string|The AWS IoT endpoint subdomain to integrate the API Gateway with (e.g a1234567890123-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|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|Optional user-provided props to override the default props for the API Gateway.| |logGroupProps?|logs.LogGroupProps|User provided props to override the default props for for the CloudWatchLogs LogGroup.|

Pattern Properties

| Name | Type | Description | |:-------------|:----------------|-----------------| |apiGateway|api.RestApi|Returns an instance of the API Gateway REST API created by the pattern.| |apiGatewayRole|iam.Role|Returns an instance of the iam.Role created by the construct for API Gateway.| |apiGatewayCloudWatchRole|iam.Role|Returns an instance of the iam.Role created by the construct for API Gateway for CloudWatch access.| |apiGatewayLogGroup|logs.LogGroup|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 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 stucture comprising a state node and associated desired and reported nodes. See the 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 stucture comprising a state node and associated desired and reported nodes. See the Updating named shadows section for an example.|

Architecture

Architecture Diagram

Examples

The following examples only work with API_KEY authentication types, since IAM authorization requires a SIGv4 token to be specified as well, make sure the apiGatewayCreateApiKey property of your Construct props is set to true while deploying the stack, otherwise the below examples won't work.

Publishing a message

You can use curl to publish a message on different MQTT topics using the HTTPS API. The below example will post a message on the device/foo topic.

curl -XPOST https://<stage-id>.execute-api.<region>.amazonaws.com/prod/message/device/foo -H "x-api-key: <api-key>" -H "Content-Type: application/json" -d '{"Hello": "World"}'

Replace the stage-id, region and api-key parameters with your deployment values.

You can chain topic names in the URL and the API accepts up to 7 sub-topics that you can publish on. For instance, the below example publishes a message on the topic device/foo/bar/abc/xyz.

curl -XPOST https://<stage-id>.execute-api.<region>.amazonaws.com/prod/message/device/foo/bar/abc/xyz -H "x-api-key: <api-key>" -H "Content-Type: application/json" -d '{"Hello": "World"}'

Updating device shadows

To update the shadow document associated with a given thing, you can issue a shadow state request using a thing name. See the following example on how to update a thing shadow.

curl -XPOST https://<stage-id>.execute-api.<region>.amazonaws.com/prod/shadow/device1 -H "x-api-key: <api-key>" -H "Content-Type: application/json" -d '{"state": {"desired": { "Hello": "World" }}}'

Updating named shadows

To update the shadow document associated with a given thing's named shadow, you can issue a shadow state request using a thing name and shadow name. See the following example on how to update a named shadow.

curl -XPOST https://<stage-id>.execute-api.<region>.amazonaws.com/prod/shadow/device1/shadow1 -H "x-api-key: <api-key>" -H "Content-Type: application/json" -d '{"state": {"desired": { "Hello": "World" }}}'

Sending binary payloads

It is possible to send a binary payload to the proxy API, down to the AWS IoT service. In the following example, we send the content of the README.md file associated with this module (treated as a binary data) to device/foo topic using the application/octet-stream content type.

curl -XPOST https://<stage-id>.execute-api.<region>.amazonaws.com/prod/message/device/foo/bar/baz/qux -H "x-api-key: <api-key>" -H "Content-Type: application/octet-stream" --data-binary @README.md

Execute this command while in the directory of this project. You can then test sending other type of binary files from your file-system.


© Copyright 2021 Amazon.com, Inc. or its affiliates. All Rights Reserved.