2.x.x

This document defines how to describe SNS-specific information on AsyncAPI.

Version

Current version is 0.2.0.

Server Binding Object

This object MUST NOT contain any properties. Its name is reserved for future use.

Channel Binding Object

This object contains information about the channel representation in SNS.

We represent an AsyncAPI Channel with a Topic in SNS. The bindings here allow definition of a topic within SNS. We provide properties on the binding that allow creation of a topic in infrastructure-as-code scenarios. Be aware that although the binding offers that flexibility, it may be more maintainable to specify properties such as SNS Access Control Policy outside of AsyncAPI.

SNS supports many optional properties. To mark a channel as SNS, but use default values for the channel properties, just use an empty object .

Fields

Field Name	Type	Description
`name`	string	Required. The name of the topic. Can be different from the channel name to allow flexibility around AWS resource naming limitations.
`ordering`	ordering	Optional. By default, we assume an unordered SNS topic. This field allows configuration of a FIFO SNS Topic.
`policy`	policy	Optional. The security policy for the SNS Topic
`tags`	Object	Optional. Key-value pairs that represent AWS tags on the topic.
`bindingVersion`	string	Optional, defaults to `latest`. The version of this binding.

Schemas

Ordering

Field Name	Type	Description
`type`	string	Required. Defines the type of SNS Topic. Can be either `standard` or `FIFO`.
`contentBasedDeduplication`	boolean	Optional. Whether the de-duplication of messages should be turned on. Defaults to `false`

Policy

Field Name	Type	Description
`statements`	[Statement]	Required. An array of Statement objects, each of which controls a permission for this topic

Statement

Field Name	Type	Description
`effect`	string	Required. Either "Allow" or "Deny"
`principal`	string or AWS principal property containing a string or string array	Required. The AWS account(s) or resource ARN(s) that the statement applies to
`action`	string or array of string	Required. The SNS permission being allowed or denied e.g. sns:Publish
`resource`	string or array of string	Optional. The resource(s) that this policy applies to
`condition`	object or list of objects	Optional. Specific circumstances under which the policy grants permission

Examples

Just use defaults

1channels:
2  user-signedup:
3    description:  A user has signed up to our service
4    bindings:
5      sns: {}

Minimal definition, just policy

1channels:
2  user-signedup:
3    description:  A user has signed up to our service
4    bindings:
5      sns:
6        policy:
7          statements: 
8          - effect : Allow
9            principal: *
10            action: SNS:Publish

Operation Binding Object

This object contains information operation binding in SNS.

We represent SNS producers via a subscribe Operation Object. In simple cases this may not require configuration, and can be shown as an empty SNS Binding Object i.e. if you need to explicitly indicate how a producer publishes to the channel.

We represent SNS consumers via a publish Operation Object. These consumers need an SNS Subscription that defines how they consume from SNS i.e. the protocol that they use, and any filters applied.

The SNS binding does not describe the receiver.If you wish to define the receiver, add a publish Operation Binding Object for that receiver. For example, if you send message to an SQS queue from an SNS Topic, you would add a protocol of 'sqs' and an Identifier object for the queue. That identifier could be an ARN of a queue defined outside of the scope of AsyncAPI, but if you wanted to define the receiver you would use the name of a queue defined in an SQS Binding on the publish Operation Binding Object.

We support an array of consumers via the consumers field. This allows you to represent multiple protocols consuming an SNS Topic in one file. You may also use it for multiple consumers with the same protocol, instead of representing each consumer in a separate file.

Fields

Field Name	Type	Applies To	Description
`topic`	identifier	Publish, Subscribe	Optional. Often we can assume that the SNS Topic is the channel name-we provide this field in case the you need to supply the ARN, or the Topic name is not the channel name in the AsyncAPI document.
`consumers`	[Consumer]	Publish	Required. The protocols that listen to this topic and their endpoints.
`deliveryPolicy`	deliveryPolicy	Subscribe	Optional. Policy for retries to HTTP. The field is the default for HTTP receivers of the SNS Topic which may be overridden by a specific consumer.
`bindingVersion`	string	Publish, Subscribe	Optional, defaults to `latest`. The version of this binding.

Schemas

Consumer

Field Name	Type	Description
`protocol`	string	Required. The protocol that this endpoint receives messages by. Can be `http`, `https`, `email`, `email-json`, `sms`, `sqs`, `application`, `lambda` or `firehose`
`endpoint`	identifier	Required. The endpoint messages are delivered to.
`filterPolicy`	object	Optional. Only receive a subset of messages from the channel, determined by this policy.
`filterPolicyScope`	string	Optional. Determines whether the FilterPolicy applies to MessageAttributes (default) or MessageBody.
`rawMessageDelivery`	boolean	Required. If true AWS SNS attributes are removed from the body, and for SQS, SNS message attributes are copied to SQS message attributes. If false the SNS attributes are included in the body.
`redrivePolicy`	redrivePolicy	Optional. Prevent poison pill messages by moving un-processable messages to an SQS dead letter queue.
`deliveryPolicy`	deliveryPolicy	Optional. Policy for retries to HTTP. The parameter is for that SNS Subscription and overrides any policy on the SNS Topic.
`displayName`	string	Optional. The display name to use with an SMS subscription

Delivery Policy

Field Name	Type	Description
`minDelayTarget`	integer	Optional. The minimum delay for a retry in seconds
`maxDelayTarget`	integer	Optional. The maximum delay for a retry in seconds
`numRetries`	integer	Optional. The total number of retries, including immediate, pre-backoff, backoff, and post-backoff retries
`numNoDelayRetries`	integer	Optional. The number of immediate retries (with no delay)
`numMinDelayRetries`	integer	Optional. The number of immediate retries (with delay)
`numMaxDelayRetries`	integer	Optional. The number of post-backoff phase retries, with the maximum delay between retries
`backoffFunction`	string, one of: arithmetic, exponential, geometric or linear	Optional. The algorithm for backoff between retries
`maxReceivesPerSecond`	integer	Optional. The maximum number of deliveries per second, per subscription

Identifier

Field Name	Type	Description
`url`	string	Optional. The endpoint is a URL
`email`	string	Optional. The endpoint is an email address
`phone`	string	Optional. The endpoint is a phone number
`arn`	string	Optional. The target is an ARN. For example, for SQS, the identifier may be an ARN, which will be of the form: "arn:aws:sqs:{region}:{account-id}:{queueName}"
`name`	string	Optional. The endpoint is identified by a name, which corresponds to an identifying field called 'name' of a binding for that protocol on this publish Operation Object. For example, if the protocol is 'sqs' then the name refers to the name field sqs binding. We don't use $ref because we are referring, not including.

We provide an Identifer Object to support providing the identifier of an externally defined endpoint for this SNS publication to target, or an endpoint on another binding against this Operation Object (via the name field).

Redrive Policy

Field Name	Type	Description
`deadLetterQueue`	Identifier	Required. The SQS queue to use as a dead letter queue (DLQ). Note that you may have a Redrive Policy to put messages that cannot be delivered to an SQS queue, even if you use another protocol to consume messages from the queue, so it is defined at the level of the SNS Operation Binding Object in a Consumer Object (and is applied as part of an SNS Subscription). The SQS Binding describes how to define an SQS Binding that supports defining the target SQS of the Redrive Policy.
`maxReceiveCount`	integer	Optional. The number of times a message is delivered to the source queue before being moved to the dead-letter queue. Defaults to 10.

Examples

We are producing to an SNS channel

1channels:
2  user-signedup:
3    description:  A user has signed up for our service
4    binding :
5      sns: {}     # Indicates that the channel is an SNS Topic
6    subscribe:
7      operationId: sendMessage
8      description: send messages to the topic
9      bindings:
10        sns:
11          consumers:
12            - protocol: sqs
13              endpoint:
14                name: myQueue
15              rawMessageDelivery: false

We are consuming an SNS channel, using an SQS queue. A separate file specifies the producer, and has the SNS Bindings for the channel. For this reason we do not repeat the SNS binding information for the channel here, to avoid duplicated definitions diverging. Instead we just define the publish Operation Binding.

In this version, the SQS queue is defined elsewhere, and we just reference via its ARN. It is worth noting that this couples the specification to the AWS region and account, which are part of the ARN, and if we moved the queue to a new region or account was this specification would need to be updated to reflect that.

1channels:
2  user-signedup:
3    description:  A user has signed up for our service
4    publish:
5      operationId: receiveMessage
6      description: receive messages from the topic
7      bindings:
8        sns:
9          consumers:
10            - protocol: sqs
11              endpoint:
12                arn: arn:aws:sqs:us-west-2:123456789012:UserSignedUpQueue
13              rawMessageDelivery: true

In this version, the SQS queue is defined in this file, and we reference it by name. For brevity that definition is not shown here. See the SQS Binding Object for more.

1channels:
2  user-signedup:
3    description:  A user has signed up for our service
4    publish:
5      operationId: receiveMessage
6      description: receive messages from the topic
7      bindings:
8        sns:
9          consumers:
10          - protocol: sqs
11            endpoint:
12              name: user-signedup-queue # refers to a queue defined in this file, but not shown in this example
13            rawMessageDelivery: true  
14            filterPolicy:
15              reason: 
16                anything-but: password-reset
17            redrivePolicy:
18              deadLetterQueue:
19                name: user-signedup-queue-dlq # refers toa queue defined in this file, but not show in this example

We are producing to an SNS channel.

In this version, we define a default delivery policy for any HTTP based consumers

1channels:
2  user-signedup:
3    description:  A user has signed up for our service
4    bindings:
5      sns:
6        policy:
7          statements: 
8          - effect : Allow
9            principal: *
10            action: SNS:Publish 
11    subscribe:
12      operationId: sendMessage
13      description: send messages to the topic
14      bindings:
15        sns:
16          deliveryPolicy:
17            minDelayTarget: 1
18            maxDelayTarget: 60
19            numRetries: 50
20            numNoDelayRetries: 3
21            numMinDelayRetries: 2
22            numMaxDelayRetries: 35
23            backoffFunction: exponential
24            maxReceivesPerSecond: 10

We are consuming an SNS channel, using an HTTP endpoint, which is defined in this AsyncAPI file. For brevity we do not show an http endpoint here. The delivery policy here is defined for the http consumer and overrides any policy set by the producer

1channels:
2  user-signedup:
3    description:  A user has signed up for our service
4    bindings:
5      sns: {}    # Indicates that the channel is an SNS Topic, but assumes defined by producer
6    publish:
7      operationId: receiveMessage
8      description: receive messages from the topic
9      bindings:
10        sns:
11        - protocol: http
12          endpoint:
13            url: http://login.my.com/user/new
14          filterPolicy:
15            reason: 
16              anything-but: password-reset
17          filterPolicyScope: MessageBody
18          deliveryPolicy:
19            minDelayTarget: 1
20            maxDelayTarget: 120
21            numRetries: 30
22            numNoDelayRetries: 3
23            numMinDelayRetries: 2
24            numMaxDelayRetries: 25
25            backoffFunction: exponential
26            maxReceivesPerSecond: 20
27          redrivePolicy:
28            deadLetterQueue:
29              name: user-signedup-queue-dlq # refers toa queue defined in this file, but not show in this example

Message Binding Object

This object MUST NOT contain any properties. Its name is reserved for future use.

On this page

2.x.x

SNS Bindings

Version

Server Binding Object

Channel Binding Object

Fields

Schemas

Ordering

Policy

Statement

Examples

Operation Binding Object

Fields

Schemas

Consumer

Delivery Policy

Identifier

Redrive Policy

Examples

SNS to SQS Pub-Sub

SNS to HTTP Pub Sub

Message Binding Object