SQS Bindings

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

SQS can be used both stand-alone as a point-to-point and paired with SNS and as a publish-subscribe channel (where SQS is the endpoint that SNS delivers messages to). For this reason we define a Queue schema, and reference that schema from both a Channel Binding Object and a publish Operation Binding Object.

For point-to-point scenarios, use the Channel Binding Object, as producers send to the queue and consumers receive from it directly.

For publish-subscribe scenarios, use as a publish Operation Binding Object, as the producer sends to SNS and the consumer receives via SQS.

Version

Current version is 0.3.0.

Server Binding Object

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

Channel Binding Object

Use the Channel Binding Operation for Point-to-Point SQS channels.

There are three likely scenarios for use of the Channel Binding Object:

• One file defines both publish and subscribe operations, for example if we were implementing the work queue pattern to offload work from an HTTP API endpoint to a worker process. In this case the channel would be defined on the Channel Object in that single file.
• The producer and consumer both have an AsyncAPI specification file, and the producer is raising an event, for example interop between microservices, and the producer 'owns' the channel definition and thus has the SQS Binding on its Channel Object.
• The producer and consumer both have an AsyncAPI specification file, and the consumer receives commands, for example interop between microservices, and the consumer 'owns' the channel definition and thus has the SQS Binding on its Channel Object.

An SQS queue can set up a Dead Letter Queue as part of a Redelivery Policy. To support this requirement, the Channel Binding Object allows you to define both a Queue Object to use as the Channel or target in a publish Operation and a Dead Letter Queue. You can then refer to the Dead letter Queue in the Redrive Policy using the Identifier Object and setting the name field to match the name field of your Dead Letter Queue Object. (If you define the DLQ externally, the Identifier also supports an ARN).

Fields

Schemas

Queue

Identifier

Policy

Redrive Policy

Statement

Operation Binding Object

SQS Point-To-Point

Because we have defined Queue as part of the Channel Binding Binding object, we do not require Binding information for the publish Operation Object of the subscribe Operation Object. You can use an empty Queue object () to denote the Binding on the Operation Object, if you want to indicate the protocol used to send or receive for generation purposes such as Infrastructure As Code.

SNS to SQS Pub-Sub

Use the Operation Binding Object when SQS is listening to an SNS Topic. In this case we need to define both an SQS Operation Binding Objects on the receiver publish Operation Object to represent the queue definition and we need to define an SNS Operation Binding Object to define the Subscription to SNS that makes your queue a receiver of that endpoint.

Assuming you have separate AsyncAPI specifications for the producer and the consumer, we would assume the following bindings would appear for an SNS producer and an SQS consumer.

Producer: SNS Channel Binding Object, SNS subscribe Operation Binding Object [if required] Consumer: SNS publish Operation Binding Object, SQS publish Operation Binding Object

• We assume that the SNS binding information only needs to be present in the producer file (although defining it in both is allowable) and any infrastructure as code dependencies can recognize this.

On an Operation Binding Object we support an array of Queue objects. Members of this array may be Queue Objects that define the endpoint field required by an SNS Operation Object delivering by the SQS protocol or Queue Objects that define the Dead Letter Queue used by either the Redrive Policy of the SNS Subscription (see the SNS Binding Object) or the Redrive Policy of the SQS Queue. The name of the Queue Object is used by an Identifier field on either the endpoint field of the SNS Operation Object of deadLetterQueue on the Redrive Policy to identify the required member of this array.

Fields

Examples

SQS Point-To-Point

In this example, we are using SQS for a point-to-point channel. For this example, we assume that we are defining two microservices that communicate over a shared SQS channel, with the consumer receiving events over that channel and the producer owning the channel definition.

The producer file would look like this:

1channels:
2  user-signedup:
3    bindings:
4      sqs:
5        queue:
6          name: user-signedup-queue
7          fifoQueue: false
8          receiveMessageWaitTime: 4
9          redrivePolicy:
10            deadLetterQueue:
11              name: user-signedup-dlq
12          policy:
13            statements: 
14            - effect : Allow
15              principal: *
16              action: Sqs:SendMessage
17            - effect : Allow
18              principal: *
19              action: Sqs:ReceiveMessage
20        deadLetterQueue: 
21          name: user-signedup-dlq 
22          messageRetentionPeriod: 1209600 
23	        fifoQueue: false
24    subscribe:
25      operationId: sendMessage
26      description: sends messages when a user has signed up
27      bindings:
28        sqs: {}
29

In this case we can minimize duplicated information by omitting the binding in our specification, and assume it is picked up from the producer file. We can use an empty object to indicate the SQS Binding on the publish Operation Object, if need a marker for generation, otherwise we could omit the Operation Binding Object.

1channels:
2  user-signedup:
3   publish:
4      operationId: receiveMessage
5      description: receives a messages when a user has signed up
6      bindings:
7        sqs: {}
8

SNS to SQS Pub-Sub

In this example, we are using SNS for the channel, and SQS to receive from SNS.

The producer files looks like this (see the SNS Binding for more).

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          policy:
12            statements: 
13            - effect : Allow
14              principal: *
15              action: SNS:Publish

And the consumer file would look like this. Note that for simplicity, we choose not to repeat the SNS Binding on the Consumer as it does not 'own' the channel.

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
13            rawMessageDelivery: true  
14            filterPolicy:
15              attributes:
16                reason: 
17                  anything-but: password-reset
18            redrivePolicy:
19              deadLetterQueue:
20              name: user-signedup-queue-dlq
21        sqs:
22          queues:
23          - name: user-signedup-queue
24            fifoQueue: false
25            receiveMessageWaitTime: 4
26            policy:
27              statements: 
28              - effect : Allow
29                principal: *
30                action: Sqs:SendMessage
31              - effect : Allow
32                principal: *
33                action: Sqs:ReceiveMessage 
34          - name: user-signedup-dlq 
35            messageRetentionPeriod: 1209600 
36            fifoQueue: false

Message Binding Object

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