Examples
This topic includes some examples of using the Control API with Curl.
In the code examples, you will need to set the following variables by any convenient method (such as setting the variables in a script, or copying and pasting suitable values directly into the code):
Variable | Description |
---|---|
ACCOUNT_ID | Your Ably Account ID (see here) |
ACCESS_TOKEN | Your Ably access token for the Control API (see here) |
APP_ID | The ID of the Ably app you want to modify or retrieve information about (see app ID) docs for more details |
Development status
Control API is currently in Preview.
Apps
You can use the Control API to perform tasks such as listing and creating Ably apps. Operations available include:
- Get a list of apps
- Create an app
- Update an app
- Delete an app
- Update an app’s APNs info
List your apps
To list all the Ably apps associated with your Ably account:
curl "https://control.ably.net/v1/accounts/${ACCOUNT_ID}/apps" \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-H "Accept: application/json"
CopyCopied!
Sample response:
[
{
"accountId": "VgQpOZ",
"id": "28GY6a",
"name": "Default",
"status": "enabled",
"tlsOnly": true,
"apnsUseSandboxEndpoint": false,
"created": 1602844091113,
"modified": 1602844093051
},
...
]
CopyCopied!
Create an app
To create an app:
curl --location --request POST 'https://control.ably.net/v1/accounts/${ACCOUNT_ID}/apps' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer ${ACCESS_TOKEN}' \
--data-raw '{
"name": "Created App 222",
"status": "enabled",
"tlsOnly": true
}'
CopyCopied!
See the API reference for information on the request body.
Sample response:
{
"accountId": "VgQpOZ",
"id": "bh4QSw",
"name": "Created App 222",
"status": "enabled",
"tlsOnly": true,
"apnsUseSandboxEndpoint": false,
"created": 1625813276973,
"modified": 1625813276973
}
CopyCopied!
Queues
You can use the Control API to manage Ably queues. The main operations are:
- List all Ably queues
- Create a queue
- Delete a queue
List queues
To list all queues associated with an app ID:
curl --location --request GET 'https://control.ably.net/v1/apps/${APP_ID}/queues' \
--header 'Authorization: Bearer ${ACCESS_TOKEN}'
CopyCopied!
Sample response:
[
{
"id": "28GY6a:us-east-1-a:Test",
"appId": "28GY6a",
"name": "Test",
"region": "us-east-1-a",
"amqp": {
"uri": "amqps://us-east-1-a-queue.ably.io:5671/shared",
"queueName": "28GY6a:Test"
},
"stomp": {
"uri": "stomp://us-east-1-a-queue.ably.io:61614",
"host": "shared",
"destination": "/amqp/queue/28GY6a:Test"
},
"state": "Running",
"messages": {
"ready": 0,
"unacknowledged": 0,
"total": 0
},
"stats": {
"publishRate": null,
"deliveryRate": null,
"acknowledgementRate": null
},
"ttl": 60,
"maxLength": 10000,
"deadletter": false,
"deadletterId": "28GY6a:us-east-1-a:deadletter"
},
...
]
CopyCopied!
Create a queue
To create a queue for an app:
curl --location --request POST 'https://control.ably.net/v1/apps/${APP_ID}/queues' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer ${ACCESS_TOKEN}' \
--data-raw '{
"name": "Queue 123",
"ttl": 60,
"maxLength": 10000,
"region": "eu-west-1-a"
}'
CopyCopied!
See the API reference for information on the request body.
Sample response:
{
"id": "28GY6a:eu-west-1-a:Queue 123",
"appId": "28GY6a",
"name": "Queue 123",
"region": "eu-west-1-a",
"amqp": {
"uri": "amqps://eu-west-1-a-queue.ably.io:5671/shared",
"queueName": "28GY6a:Queue 123"
},
"stomp": {
"uri": "stomp://eu-west-1-a-queue.ably.io:61614",
"host": "shared",
"destination": "/amqp/queue/28GY6a:Queue 123"
},
"state": "Unknown",
"messages": {
"ready": 0,
"unacknowledged": 0,
"total": 0
},
"stats": {
"publishRate": null,
"deliveryRate": null,
"acknowledgementRate": null
},
"ttl": 60,
"maxLength": 10000,
"deadletter": false,
"deadletterId": "28GY6a:eu-west-1-a:deadletter"
}
CopyCopied!
Keys
You can use the Control API to manage Ably API keys. The main operations are:
- List all Ably API keys for an app
- Create a key
- Update a key
- Revoke a key
Control API enables you to create a key that has different capabilities for different channels.
List API keys
To list all keys associated with an app ID:
curl --location --request GET 'https://control.ably.net/v1/apps/${APP_ID}/keys' \
--header 'Authorization: Bearer ${ACCESS_TOKEN}'
CopyCopied!
Sample response:
[
{
"appId": "28GY6a",
"id": "-frw5Q",
"name": "Control API Key",
"key": "28GY6a.-frw5Q:ZHTaEUGGJWJtHSkZ",
"capability": {
"channel-1": [
"publish"
]
},
"created": 1630074457007,
"modified": 1630074457007
},
...
]
CopyCopied!
Create a key
The following example demonstrates how to create an Ably API key:
curl --location --request POST 'https://control.ably.net/v1/apps/${APP_ID}/keys' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer ${ACCESS_TOKEN}' \
--data-raw '{
"name": "My key name",
"capability": {
"channel1": [
"publish",
"subscribe"
],
"channel2": [
"history"
]
}
}'
CopyCopied!
This request creates an API key with the key name My key name
. Note that this key specifies different capabilities for each channel, for example, on channel1
this key has publish and subscribe capabilities. On channel2
the key only has the history capability.
Sample response:
{
"appId": "28GY6a",
"id": "Eg063g",
"name": "My key name",
"key": "28GY6a.Eg063g:Dp9ZNfK6Qr8aWy-q",
"capability": {
"channel1": [
"publish",
"subscribe"
],
"channel2": [
"history"
]
},
"created": 1630506079278,
"modified": 1630506079278
}
CopyCopied!
Update a key
The following request updates the key name, and also adds the history capability to channel1
:
curl --location --request PATCH 'https://control.ably.net/v1/apps/${APP_ID}/keys/${KEY_ID}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer ${ACCESS_TOKEN}' \
--data-raw '{
"name": "My key name UPDATED",
"capability": {
"channel1": [
"publish",
"subscribe",
"history"
],
"channel2": [
"history"
]
}
}'
CopyCopied!
Sample response:
{
"appId": "28GY6a",
"id": "RCSMrg",
"name": "My key name UPDATED",
"key": "28GY6a.RCSMrg:z8HkAtY7rMtnpcGq",
"capability": {
"channel1": [
"history",
"publish",
"subscribe"
],
"channel2": [
"history"
]
},
"created": 1630507628335,
"modified": 1630507811349
}
CopyCopied!
Revoke a key
To revoke a specific key for a specific app:
curl --location --request POST 'https://control.ably.net/v1/apps/${APP_ID/keys/${KEY_ID}/revoke' \
--header 'Authorization: Bearer ${ACCESS_TOKEN}'
CopyCopied!
In this case there is only a status code returned (200), or an error code.
Rules
You can use the Control API to manage Ably integration rules. The main operations are:
- List all rules for an app
- List details of a specific rule using rule ID
- Create a rule
- Update a rule
- Delete a rule
List rules
To list the rules for an app:
curl --location --request GET 'https://control.ably.net/v1/apps/${APP_ID}/rules' \
--header 'Authorization: Bearer ${ACCESS_TOKEN}'
CopyCopied!
Sample response:
[
{
"id": "oO-Tug",
"appId": "28GY6a",
"ruleType": "http",
"requestMode": "single",
"status": "disabled",
"source": {
"channelFilter": "",
"type": "channel.message"
},
"target": {
"url": "https://example.com/webhooks",
"signingKeyId": null,
"enveloped": true,
"format": "json",
"headers": [
{
"name": "User-Agent",
"value": " user-agent-name"
}
]
},
"version": "1.0",
"created": 1626893758695,
"modified": 1626894987810,
"_links": {
"self": "https://control.ably.net/v1/apps/28GY6a/rules/oO-Tug"
}
},
...
]
CopyCopied!
List a rule by rule ID
curl --location --request GET 'https://control.ably.net/v1/apps/${APP_ID}/rules/${RULE_ID}' \
--header 'Authorization: Bearer ${ACCESS_TOKEN}'
CopyCopied!
The rule details are returned for the specified rule.
Create a rule
The following example creates a rule with the following configuration
Parameter | Value | Description |
---|---|---|
ruleType | http | The type of rule, in this case a webhook rule |
requestMode | single | Request mode can be single or batched |
channelFilter | ^my-channel.* | An optional regular expression that allows the rule to be applied to the specified channel set |
type | channel.message | Source type. This means that the source event that will trigger this rule is any message on the channel |
url | https://example.com/webhooks | The webhook endpoint. This is the URL triggered for the event |
format | json | Format of encoding for the rule, in this case JSON |
name | User-Agent | Optional header or headers, including custom headers that might be required. In this case a user agent header is specified (this needs to be set for some providers) |
value | user-agent-name | The value of the header |
enveloped | true | Wrap packet in metadata |
The corresponding request is:
curl --location --request POST 'https://control.ably.net/v1/apps/${APP_ID}/rules' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer ${ACCESS_TOKEN}' \
--data-raw '{
"ruleType": "http",
"requestMode": "single",
"source": {
"channelFilter": "^my-channel.*",
"type": "channel.message"
},
"target": {
"url": "https://example.com/webhooks",
"format": "json",
"headers": [
{
"name": "User-Agent",
"value": "user-agent-string"
},
{
"name": "headerName",
"value": "headerValue"
}
],
"enveloped": true
}
}'
CopyCopied!
Sample response:
{
"id": "3DySkw",
"appId": "28GY6a",
"ruleType": "http",
"requestMode": "single",
"status": "enabled",
"source": {
"channelFilter": "^my-channel.*",
"type": "channel.message"
},
"target": {
"url": "https://example.com/webhooks",
"signingKeyId": null,
"enveloped": true,
"format": "json",
"headers": [
{
"name": "User-Agent",
"value": "user-agent-string"
},
{
"name": "headerName",
"value": "headerValue"
}
]
},
"version": "1.0",
"created": 1630588265781,
"modified": 1630588265781,
"_links": {
"self": "https://control.ably.net/v1/apps/28GY6a/rules/3DySkw"
}
}
CopyCopied!
This shows the created webhook rule.
Update a rule
If you need to change a rule you can update it. For example, if you wanted to change the webhook endpoint URL you could carry out the following request:
curl --location --request PATCH 'https://control.ably.net/v1/apps/${APP_ID}/rules/${RULE_ID}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer ${ACCESS_TOKEN}' \
--data-raw '{
"ruleType": "http",
"target": {
"url": "https://example.com/webhooks/webhook1"
}
}'
CopyCopied!
The response is the same as for rule creation, but reflects the updated information.
Delete a rule
If you need to delete a rule you can:
curl --location --request DELETE 'https://control.ably.net/v1/apps/${APP_ID}/rules/${RULE_ID}' \
--header 'Authorization: Bearer ${ACCESS_TOKEN}'
CopyCopied!
In this case there is only a status code returned (204), or an error code.