NATS API

The Neural Autonomic Transport System, or NATS, is an open-source messaging system written in Go. It is part of the Cloud Native Computing Foundation (CNCF) and has more than 40 client language implementations. The application has been designed with performance, scalability, and ease of use in mind. If you're new to NATS, you can learn more about it on our NATS overviewOpen in new context page.

(switchcolumn)

Concepts

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

(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. Create a NATS account. A NATS account provides a scope for your NATS streams, messages and credentials.

   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/nats-accounts" \
       -d '{
         "name": "my-nats-account",
         "project_id": "'$SCW_PROJECT_ID'"
       }' | tee my-nats-account.json | jq

   Tip

   • | tee my-nats-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 the NATS service. The nats_account_id field is automatically set to the value of id returned by the previous command:

   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/nats-credentials" \
       -d '{
         "name": "my-credentials",
         "nats_account_id": "'$(jq -r .id my-nats-account.json)'"
       }' | tee my-nats-credentials.json | jq

4. Extract the credentials you created in the previous step:

   Code
   jq -r .credentials.content my-nats-credentials.json > nats.creds

5. Publish your first message with the NATS CLI. Open two terminals for this purpose.

   • On terminal 1: subscribe to a subject

     Code
     nats sub -s $(jq -r .endpoint my-nats-account.json) --creds nats.creds my-subject

   • On terminal 2: publish a message to this subject:

     Code
     nats pub -s $(jq -r .endpoint my-nats-account.json) --creds nats.creds my-subject 'Hi there!'

   The "Hi there!" message should appear on the terminal 1. You can now abort the subscription by typing "CTRL+C" on terminal 1.

6. Delete the NATS account

   Code
   curl --silent -X DELETE \
     -H "X-Auth-Token: $SCW_SECRET_KEY" \
     -H "Content-Type: application/json" \
       "https://api.scaleway.com/mnq/v1beta1/regions/fr-par/nats-accounts/$(jq -r .id my-nats-account.json)" | 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 natscliOpen in new context (choose your installation method between go install, .zip download or .deb installation)
• You have installed jqOpen in new context

Technical limitations

The maximum storage capacity of a NATS account is 300 MB. Be aware that replicates are counted into this quota.

Technical information

Regional availability

Scaleway NATS is currently available in the following regions:

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

NATS credentials

Credentials give full access to the NATS account. Isolation can be handled by using several NATS accounts.

TLS

Note that the Scaleway NATS server is configured with TLS, and as such will require all clients to connect with TLS. In the case of the NATS SDK however, the SDK abstracts this and handles the TLS connection itself.

Going further

For more help using Scaleway NATS, 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 official NATS documentation:

• What is NATSOpen in new context
• Installing & using the NATS CLIOpen in new context
• JetStream official documentationOpen in new context (JetStream is enabled with quotasOpen in new context on our servers)
• Official NATS GitHubOpen in new context: official client library for many languages (golangOpen in new context, pythonOpen in new context, rustOpen in new context etc.) and many other coding resources
• NATS community Slack channelOpen in new context.