Protocol Subscription

Subscription Object

subscription object represents a subscription of record changes by a specific device. A subscription observes on a set of records. If a record is added to, removed from, or modifed in that set, server will trigger a slient notification to the registered device.

Object definition

Explanation with an example object in JSON format:

{
	// `id` (string, required)
	// The unique identifier of the subscription.
	"id": "subscription_id",

	// `type` (string, required)
	// The type of subscription. It is the method for this subscription
	// to determine the set of records to observe on. Currently only
	// `query` is supported.
	"type": "query",

	// `query` (object, required when `type`="query")
	// The query to define the set of records which this subscription
	// is observing. See [[Protocol-Query]] for details.
	"query": {

		// `record_type` (string, required)
		// The type of records to observe on this query
		"record_type": "RECORD_TYPE",

		// `predicate` (object, *optional* at the moment)
		// The predicate object used to define the set of records to be
		// observed on. See [[Protocol-Query]] for how this object is
		// constructed.
		//
		// This attribute is not supported currently.
		"predicate": {"content": "undefined"}
	}
}

Returning errors

All actions of this endpoint are batch operations. If the server failed to process to batch process of subscription. result field in the response will be an error object signifying the reason. If the server is able to batch process the subscriptions, the Result field will be an list of object.

See Protocol-Record#returning-error for an illustration of such errors.

subscription:save

Overview

Create and modify subscriptions in a specific database.

device_id is required to call this endpoint, which can obtained by calling device:register. See Protocol-Device for details.

Parameters

• access_token (string, required)

  The access token associated with the user of this request.

• database_id (string, required)

  The id of database to create / modify the subscriptions. It is either _public or _private.

• device_id (string, required)

  The id of the device to receive notifications triggered by the subscriptions.

• subscriptions (list of subscription objects, required)

  List of subscription objects to create / modify on the server.

Responses

• database_id (string)

  The id of the database which this endpoint was operated on.

• device_id (string)

  The id of the device which this endpoint was operated on.

• result (error object, or list of objects)

  Error object is returned if the server is unable to start processing any parts of the request.

  Otherwise, for every subscription in the request parameter, either one of the following is returned.

  1. If the subscription was created / modifed successfully, the created / modifed subscription is returned.

  2. If the server failed to create / modify the subscription, an error is returned.

subscription:delete

Overview

Delete one or more records in a specific database.

Parameters

• access_token (string, required)

  The access token associated with the user of this request.

• database_id (string, required)

  The id of database to create / modify the subscriptions. It is either _public or _private.

• subscription_ids (list of string)

  List of subscription object ids to delete on the server.

Responses

• database_id (string)

  The id of the database which this endpoint was operated on.

• result (error object, or list of objects)

  Similar to the Responses section under subscription:save.

Discussion

• You can see the notification_info part defined in ODKit has vanished. It is after a disuccsion with @rickmak, then I decided to remove it for two reasons.

  1. The removal of user notification lessen the distraction of user notification and make the api of subscription more concentrated on data synchronization. Thus, easier to understand.

  2. We already have API to send push notification. There doesn't seem to have cases in this api not covered by that.

  3. The notification message achievable by this API is of lesser value. notification_info can only show static content. e.g. "You have got a message" in a chatting app is certainly not very helpful.