Subscriptions

Updated
Cover image for: Subscriptions

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()

How can we help?

Our support team are here to help!

Our office hours are Monday to Friday, 9 AM to 5 PM GMT. The time is currently 5:26 AM GMT.

We aim to reply to all messages within one working day.

Go to support section › Contact the enterprise team ›
Our awesome support team

© 2008 - 2020 Reincubate Ltd. All rights reserved. Registered in England and Wales #5189175, VAT GB151788978. Reincubate® is a registered trademark. Privacy policy & terms. We recommend 2FA. Built with in London.