A Sync ListItem is an object you have added to a Sync List.
You need to create a List before you can use this resource to create, read, update, and delete items within it.
Sync Lists generally behave like arrays in most programming languages. However, when working with ListItems, keep these details in mind:
The automatically generated index of the List Item. The index
values of the List Items in a Sync List can have gaps in their sequence.
An arbitrary, schema-less object that the List Item stores. Can be up to 16 KiB in length.
The date and time in GMT when the List Item expires and will be deleted, specified in ISO 8601 format. If the List Item does not expire, this value is null
. The List Item resource might not be deleted immediately after it expires.
The date and time in GMT when the resource was created specified in ISO 8601 format.
The date and time in GMT when the resource was last updated specified in ISO 8601 format.
The identity of the List Item's creator. If the item is created from the client SDK, the value matches the Access Token's identity
field. If the item was created from the REST API, the value is system
.
POST https://sync.twilio.com/v1/Services/{ServiceSid}/Lists/{ListSid}/Items
The SID of the Sync List to add the new List Item to. Can be the Sync List resource's sid
or its unique_name
.
A JSON string that represents an arbitrary, schema-less object that the List Item stores. Can be up to 16 KiB in length.
An alias for item_ttl
. If both parameters are provided, this value is ignored.
How long, in seconds, before the List Item expires (time-to-live) and is deleted.
How long, in seconds, before the List Item's parent Sync List expires (time-to-live) and is deleted.
_10syncClient.list('example_list').then(function(list) {_10 list.push({_10 text: 'hello world',_10 user: 'Charles Xavier'_10 }).then(function(item) {_10 console.log('Added: ', item.index);_10 }).catch(function(err) {_10 console.error(err);_10 });_10});
Note: There are two separate events for list item adds and list item updates:
_12syncClient.list('example_list').then(function(list) {_12 list.on('itemAdded', function(item) {_12 console.log('index', item.index);_12 console.log('JSON data', item.value);_12 });_12_12//Note that there are two separate events for list item adds and list item updates:_12 list.on('itemUpdated', function(item) {_12 console.log('index', item.index);_12 console.log('JSON data', item.value);_12 });_12});
GET https://sync.twilio.com/v1/Services/{ServiceSid}/Lists/{ListSid}/Items/{Index}
The SID of the Sync List with the Sync List Item resource to fetch. Can be the Sync List resource's sid
or its unique_name
.
Fetch only the first item
Fetch only the first item
_10syncClient.list('example_list').then(function(list) {_10 list.get(0).then(function(item) {_10 console.log('show first item', item);_10 });_10});
GET https://sync.twilio.com/v1/Services/{ServiceSid}/Lists/{ListSid}/Items
Retrieve all items belonging to a List.
By default, this will return the first 50 List items. Supply a PageSize argument to fetch up to 100 items at once.
See paging for more information.
The SID of the Sync List with the List Items to read. Can be the Sync List resource's sid
or its unique_name
.
How to order the List Items returned by their index
value. Can be: asc
(ascending) or desc
(descending) and the default is ascending.
asc
desc
The index
of the first Sync List Item resource to read. See also bounds
.
Whether to include the List Item referenced by the from
parameter. Can be: inclusive
to include the List Item referenced by the from
parameter or exclusive
to start with the next List Item. The default value is inclusive
.
inclusive
exclusive
How many resources to return in each list page. The default is 50, and the maximum is 1000.
Get 20 items from a SyncList
Display the first item only
_10syncClient.list('example_list').then(function(list) {_10 list.getItems().then(function(page) {_10 console.log('show first item', page.items[0]);_10 });_10});
POST https://sync.twilio.com/v1/Services/{ServiceSid}/Lists/{ListSid}/Items/{Index}
If provided, applies this mutation if (and only if) the “revision” field of this [map item] matches the provided value. This matches the semantics of (and is implemented with) the HTTP If-Match header.
The SID of the Sync List with the Sync List Item resource to update. Can be the Sync List resource's sid
or its unique_name
.
A JSON string that represents an arbitrary, schema-less object that the List Item stores. Can be up to 16 KiB in length.
An alias for item_ttl
. If both parameters are provided, this value is ignored.
How long, in seconds, before the List Item expires (time-to-live) and is deleted.
How long, in seconds, before the List Item's parent Sync List expires (time-to-live) and is deleted. This parameter can only be used when the List Item's data
or ttl
is updated in the same request.
Use the set method to change the data in a ListItem
_10syncClient.list('example_list').then(function (list) {_10 var newValue = {_10 text: 'hello world',_10 user: 'Wolverine'_10 };_10 list.set(0, newValue).then(function(item) {_10 console.log('updated first item', item);_10 });_10});
Please note: Using set
will overwrite any existing data in a list item.
Use the update method to change data in a ListItem.
_10syncClient.list('example-list').then(function(list) {_10 list.update(0,{user: "Magneto"});_10});
Use mutate for more fine-grained control
_10syncClient.list('example-list').then(function (list) {_10 list.mutate(0,function(remoteData) {_10 remoteData.user = "Cyclops";_10 return remoteData;_10 });_10});
The mutate
function helps your Javascript code respond to concurrent updates with versioned control. See the corresponding JavaScript SDK documentation for details.
Note: There are two separate events for list item adds and list item updates:
_12syncClient.list('example_list').then(function(list) {_12 list.on('itemAdded', function(item) {_12 console.log('index', item.index);_12 console.log('JSON data', item.value);_12 });_12_12//Note that there are two separate events for list item adds and list item updates:_12 list.on('itemUpdated', function(item) {_12 console.log('index', item.index);_12 console.log('JSON data', item.value);_12 });_12});
DELETE https://sync.twilio.com/v1/Services/{ServiceSid}/Lists/{ListSid}/Items/{Index}
If provided, applies this mutation if (and only if) the “revision” field of this [map item] matches the provided value. This matches the semantics of (and is implemented with) the HTTP If-Match header.
The SID of the Sync List with the Sync List Item resource to delete. Can be the Sync List resource's sid
or its unique_name
.
Deletes the 0-indexed item in the Sync List
Deletes the 0-index item in a Sync List
_10syncClient.list('example_list').then(function(list) {_10 list.remove(0).then(function() {_10 console.log('deleted first item');_10 });_10});