A subscription object represents a continuing request for data, such as "retrieve new CallKit calls every 24 hours" or "retrieve the latest iOS messages from a Reincubate Relay source when a new backup is made".
Different services can implement subscriptions in slightly different ways. The iCloud service works on a periodic polling mechanism, whereby it checks for new data every set interval of time. The rirelay service works on a push mechanism, publishing new data as soon as it becomes available.
Attributes
| name | type | description |
|---|---|---|
id | string | Resource identifier. |
resource | string, always subscription | Resource type identifier. |
org | organisation ID | The subscription's associated organisation. |
source | source ID | |
session | session ID | |
poll_payload | nested poll payload | The payload of polls to be created by the subscription. See poll payload. |
interval | optional timedelta | The interval between polls, in seconds. |
date_start | optional datetime | The date to start creating polls. |
date_end | optional datetime | The date to stop creating polls. |
state | string | One of: pending, active, deleted. |
date_created | datetime | When the resource was created. |
Interval
The interval attribute controls the frequency at which the API will pull in or request new data from a source.
On the iCloud service, which is pull-based, the subscription will create a new poll every interval seconds.
On the Reincubate Relay service, the interval attribute is instead passed through to the Relay app. This configures how often the app will request new data from connected devices, wish then triggers a poll on the API via a push mechanism. No poll is created until the device associated with the subscription's source is connected to the Relay app.
Create POST /subscriptions
| name | type | description |
|---|---|---|
session | session ID | Which session to create polls against. |
source | optional, source ID | Optionally target a child source of the session-linked source. |
poll_payload | nested poll payload | The poll payload used to specify poll |
interval | optional timedelta | The interval between polls, in seconds. |
date_start | optional datetime | The date to start creating polls. |
date_end | optional datetime | The date to stop creating polls. |
Using cURL
curl https://ricloud-api.reincubate.com/subscriptions \
-X POST \
-H 'Authorization: Token <your key_token>' \
-H 'Content-Type: application/json' \
-d '{
"session": "<session ID>",
"source": "<source ID>",
"poll_payload": {
"data_types": ["ios_messages.messages", "whatsapp.messages"]
}
}'
Using ricloud-py
import ricloud
poll_payload = {
"data_types": ["ios_messages.messages", "whatsapp.messages"],
}
subscription = ricloud.Subscription.create(
session="<session ID or ricloud.Session instance>",
source="<source ID or ricloud.Source instance>",
poll_payload=poll_payload,
)
Retrieve GET /subscriptions/{subscription ID}
Using cURL
curl https://ricloud-api.reincubate.com/subscriptions/<subscription ID> \
-H 'Authorization: Token <your key_token>'
Using ricloud-py
import ricloud
subscription = ricloud.Subscription.retrieve(<subscription ID>)
List GET /subscriptions
Using cURL
curl https://ricloud-api.reincubate.com/subscriptions \
-H 'Authorization: Token <your key_token>'
Using ricloud-py
import ricloud
subscriptions = ricloud.Subscription.list()
Update POST /subscriptions/{subscription ID}
A subscription can be updated to change the polls it creates and when it creates them.
Also, in the case a subscription's session expires it can be replaced with a newly created, active session.
| name | type | description |
|---|---|---|
session | session ID | Which session to create polls against. Must have the same underlying source as the subscription's original session. |
poll_payload | nested poll payload | The poll payload used to specify poll. |
interval | optional timedelta | The interval between polls, in seconds. |
date_start | optional datetime | The date to start creating polls. |
date_end | optional datetime | The date to stop creating polls. |
Using cURL
curl https://ricloud-api.reincubate.com/subscriptions/<subscription ID> \
-X POST \
-H 'Authorization: Token <your key_token>' \
-H 'Content-Type: application/json' \
-d '{
"session": "<session ID>",
"poll_payload": {
"data_types": ["icpl.photos"]
}
}'
Using ricloud-py
import ricloud
poll_payload = {
"data_types": ["icpl.photos"],
}
subscription = ricloud.Subscription.update(
session="<session ID or ricloud.Session instance>",
poll_payload=poll_payload,
)
Delete DELETE /subscriptions/{subscription ID}
Stop the subscription from creating further polls.
Using cURL
curl https://ricloud-api.reincubate.com/subscriptions/<subscription ID> \
-X DELETE \
-H 'Authorization: Token <your key_token>'
Using ricloud-py
import ricloud
subscription = ricloud.Subscription.delete_with_id(<subscription ID>)
# OR
subscription = ricloud.Subscription.retrieve(<subscription ID>)
subscription.delete()