Messaging and Queuing SNS API

Introduction

The Simple Notification Service, or SNS, is a managed messaging service developed by AWS and supported by Scaleway Message and Queuing. If you're new to SNS, you can learn more about it on our SQS/SNS overview page.

Important:

Please note that SNS is still in Public Beta. We do not guarantee performance or stability. Use with care, as you may encounter data loss.

Tip:

If SNS is not the Messaging and Queuing service you're looking for, check out our NATS or SQS services. You can also consult the legacy v1alpha1 API. We strongly recommend you read our dedicated documentation to find out more about the migration from v1alpha1 to v1beta1. SNS users must manually migrate to v1beta1 by recreating their resources. v1alpha1 will soon be deprecated, and all non-migrated resources will be lost.

Concepts

Refer to our dedicated concepts page to find definitions of all terminology related to Messaging and Queuing.

Quickstart

  1. Configure your environment variables

    Note:

    This is an optional step that seeks to simplify your usage of the API.

    export SCW_SECRET_KEY="<API secret key>"
    export SCW_PROJECT_ID="<Scaleway Project ID>"
  2. Activate the SNS protocol on your Scaleway Project:

    curl --silent -X POST \
    -H "X-Auth-Token: $SCW_SECRET_KEY" \
    -H "Content-Type: application/json" \
    "https://api.scaleway.com/mnq/v1beta1/regions/fr-par/activate-sns" \
    -d '{
    "project_id": "'$SCW_PROJECT_ID'"
    }' | jq
    curl --silent -X GET \
    -H "X-Auth-Token: $SCW_SECRET_KEY" \
    -H "Content-Type: application/json" \
    "https://api.scaleway.com/mnq/v1beta1/regions/fr-par/sns-info?project_id=$SCW_PROJECT_ID" \
    | tee my-sns-account.json | jq
    Tip:
    • | tee my-sns-account.json saves the JSON object returned by the API to a file (used by next steps)
    • | jq displays the output nicely
  3. Create credentials. Credentials are necessary to authenticate a client to your SNS service. Their permissions should be specified and adapted according to your needs, using true or false for each type of permission.

    curl --silent -X POST \
    -H "X-Auth-Token: $SCW_SECRET_KEY" \
    -H "Content-Type: application/json" \
    "https://api.scaleway.com/mnq/v1beta1/regions/fr-par/sns-credentials" \
    -d '{
    "name": "my-credentials",
    "permissions": {
    "can_publish": true,
    "can_receive": true,
    "can_manage": true
    },
    "project_id": "'$SCW_PROJECT_ID'"
    }' | tee my-sns-credentials.json | jq
  4. Export credentials: Export the credentials to your environment:

    export AWS_ENDPOINT_URL=$(jq -r .sns_endpoint_url my-sns-account.json)
    export AWS_ACCESS_KEY_ID=$(jq -r .access_key my-sns-credentials.json)
    export AWS_SECRET_ACCESS_KEY=$(jq -r .secret_key my-sns-credentials.json)
  5. Start creating topics and publishing messages. The following commands show you how to create a topic, subscribe to a Scaleway Serverless function, and send, receive and delete a message.

    aws sns create-topic --name my-topic | tee my-topic.json
    aws sns subscribe --topic-arn "$(jq -r .TopicArn my-topic.json)" \
    --protocol lambda --notification-endpoint <YOUR-FUNCTION-ENDPOINT>
    aws sns publish --topic-arn "$(jq -r .TopicArn my-topic.json)" \
    --message 'Hello world!'
  6. Disable SNS

    Important:

    Disabling SNS deletes all topics and messages stored in your SNS service.

    curl --silent -X POST \
    -H "X-Auth-Token: $SCW_SECRET_KEY" \
    -H "Content-Type: application/json" \
    "https://api.scaleway.com/mnq/v1beta1/regions/fr-par/deactivate-sns" \
    -d '{
    "project_id": "'$SCW_PROJECT_ID'"
    }' | jq
Requirements:

Technical limitations

Scaleway Messaging and Queuing does not support the entire set of AWS SNS actions or parameters. See the compatibility matrix for more information.

Also note that:

  • The maximum message size is 256 kB.
  • The maximum storage capacity for all topics of a project is 100 MB.

Technical information

Regional availability

Scaleway Messaging and Queuing is currently only available in the Paris, France region (fr-par).

SNS credentials

Credentials use a simplified permissions system with 3 permissions:

  • can_publish : allows to publish messages to a Topic.
  • can_receive : allows to subscribe to a topic.
  • can_manage : allows all other actions (Creating, Listing, Updating, Deleting Topics).

Each set of credentials gives access to all topics. Isolation can be handled by using several Scaleway Projects.

Going further

For more help using Scaleway Messaging and Queuing, check out the following resources:

You can also read the AWS SNS documentation.

SNS

SNS (Simple Notification System) provides a notification service. It must be activated per Project before being used

POST
/mnq/v1beta1/regions/{region}/activate-sns
POST
/mnq/v1beta1/regions/{region}/deactivate-sns
GET
/mnq/v1beta1/regions/{region}/sns-info

SNS credentials

SNS credentials give access to the SNS service

GET
/mnq/v1beta1/regions/{region}/sns-credentials
POST
/mnq/v1beta1/regions/{region}/sns-credentials
GET
/mnq/v1beta1/regions/{region}/sns-credentials/{sns_credentials_id}
PATCH
/mnq/v1beta1/regions/{region}/sns-credentials/{sns_credentials_id}
DELETE
/mnq/v1beta1/regions/{region}/sns-credentials/{sns_credentials_id}