Topics and Events API
Introduction
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 overview page.
Concepts
Refer to our dedicated concepts page to find definitions of all terminology related to NATS, Queues, and Topics and Events.
Quickstart
-
Configure your environment variables
NoteThis 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>" -
Activate Topics and Events 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'"}' | jqcurl --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 | jqTip| 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
-
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
orfalse
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 -
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) -
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.jsonaws 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!' -
Disable Topics and Events
ImportantDisabling Topics and Events deletes all topics and messages stored in your Topics and Events 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
- You have a Scaleway account
- You have created an API key and that the API key has sufficient IAM permissions to perform the actions described on this page
- You have installed
curl
- You have installed awscli v1 (version >= 1.29.0) or awscli v2 (version >= 2.13.0)
- You have installed jq
Technical limitations
Scaleway Topics and Events 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 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 Projects.
Going further
For more help using Scaleway Topics and Events, check out the following resources:
- Our main documentation
- The
#messaging-queuing
channel on our Slack community - Our support ticketing system
You can also read the AWS SNS documentation.
Topics and Events
Topics and Events 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
Topics and Events credentials
Topics and Events credentials give access to the Topics and Events 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}