Topics and Events API

Topics and Events is a managed messaging service provided by Scaleway. It supports the API developed by Amazon with its Simple Notification Service, or Amazon SNS. If you're new to Topics and Events, you can learn more about it on our Topics and Events overviewOpen in new context page.

(switchcolumn)

Concepts

Refer to our dedicated concepts pageOpen in new context to find definitions of all terminology related to Topics and Events.

(switchcolumn) (switchcolumn)

Quickstart

1. Configure your environment variables

   Note

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

   Code
   export SCW_SECRET_KEY="<API secret key>"
   export SCW_PROJECT_ID="<Scaleway Project ID>"

2. Activate Topics and Events on your Scaleway Project:

   Code
   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 Topics and Events service. Their permissions should be specified and adapted according to your needs, using true or false for each type of permission.

   Code
   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:

   Code
   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 functionOpen in new context, and send, receive and delete a message.

   Code
   aws sns create-topic --name my-topic | tee my-topic.json

   Code
   aws sns subscribe --topic-arn "$(jq -r .TopicArn my-topic.json)" \
     --protocol lambda --notification-endpoint <YOUR-FUNCTION-ENDPOINT>

   Code
   aws sns publish --topic-arn "$(jq -r .TopicArn my-topic.json)" \
     --message 'Hello world!'

6. Disable Topics and Events

   Important

   Disabling Topics and Events deletes all topics and messages stored in your Topics and Events service.

   Code
   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

(switchcolumn)

• You have a Scaleway accountOpen in new context
• You have created an API keyOpen in new context and that the API key has sufficient IAM permissionsOpen in new context to perform the actions described on this page
• You have installed curlOpen in new context
• You have installed awscli v1Open in new context (version >= 1.29.0) or awscli v2Open in new context (version >= 2.13.0)
• You have installed jqOpen in new context

(switchcolumn)

Technical limitations

Scaleway Topics and Events does not support the entire set of AWS SNS actions or parameters. See the compatibility matrixOpen in new context 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 Topics and Events is currently available in the following regions:

• Paris, France (fr-par)
• Amsterdam, Netherlands (nl-ams)

Topics and Events 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 ProjectsOpen in new context.

Going further

For more help using Scaleway Topics and Events, check out the following resources:

• Our main documentationOpen in new context
• The #messaging-queuing channel on our Slack communityOpen in new context
• Our support ticketing systemOpen in new context

You can also read the AWS SNS documentationOpen in new context.