XML-RPC API.Methods: Collection
collection.create
Creates a new collection as defined by the supplied collection object.
collection.create(type, name, query [,options])parameters
| type | string | Available values: user, video, collection. Specifies the type of the collection to create. |
|---|---|---|
| name | string | Required. Name of the collection. |
| query | object | Required. A query object suitable for collection.find / video.find / user.find. This defines the members of the collection. |
options
| owner | string | Optional. Owner of the collection. This must be either the authenticated user, or one of their children |
|---|---|---|
| description | string | Optional. Description of the collection |
| additional | object | Optional. Optional argument which allows arbitrary key/value pairs of information about the collection to be stored. Can only be updated for children of the authenticated user. |
| subtype | string | Optional. An optional arbitrary searchable subtype to assign the collection. can only be updated for children of the authenticated user. |
| restrictions | integer | Optional.
Can set restrictions for collections owned by children of the authenticated user. Default is 0 |
returns
The id of the newly created collection
errors
In addition to the global API errors, this function can return the following local errors:
| 1101 | Insufficient permission to create collection |
|---|---|
| 1102 | Invalid query |
| 1103 | Cannot restrict your own collection |
collection.update
Updates the details of a collection. Only collections of the authenticated user, or their descendents can be updated. If the collection belongs directly to the authenticated user, then it can only be updated if restrictions are less than 2.
collection.update(id, collection)parameters
| id | integer | Id of the collection to update |
|---|---|---|
| collection | object | |
| name | string | Optional. Name of the collection |
| query | object | Optional. A query object suitable for collection.find / video.find / user.find. This defines the members of the collection. |
| description | string | Optional. Description of the collection. |
| additional | object | Optional. Optional argument which allows arbitrary key/value pairs of information about the collection to be stored. Can only be updated for children of the authenticated user. |
| subtype | string | Optional. Updates the arbitrary subtype parameter. |
errors
In addition to the global API errors, this function can return the following local errors:
| 1100 | Invalid collection id |
|---|---|
| 1101 | Insufficient permission to update collection |
| 1102 | Invalid query |
| 1103 | Cannot update a restricted collection |
collection.delete
Deletes the collection with the ids supplied. Only collections of the authenticated user, or their children can be deleted. If a collection belongs directly to the authenticated user, then it can only be deleted if restrictions are less than 1.
collection.delete(ids)parameters
| ids | array of integers | Ids to delete |
|---|
returns
Returns true on success.
errors
In addition to the global API errors, this function can return the following local errors:
| 1100 | Invalid collection id |
|---|---|
| 1101 | Insufficient permission to delete collection |
| 1103 | Cannot delete a restricted collection |
collection.find
Returns collections which match the supplied query filter.
collection.find(query, returnFields [,options])parameters
| query | object | Filter requirements for collections returned |
|---|---|---|
| ids | array of integers | Returns collections with these ids |
| owners | array of strings | Returns collections with these owners |
| names | array of strings | Returns collections with the given names. Names are matched case insensitive |
| types | array of strings | Possible values: video, user, collection Returns collections of the specified type only |
| subtypes | array of strings | Returns collections of specified subtypes |
returnFields
Specifies the level of detail returned for collections matched by the query.
| id | integer | Id of the media |
|---|---|---|
| owner | string | Owner of the collection |
| name | string | Name of the collection |
| type | string | Type of collection (video, user, collection) |
| subtype | string | Arbitrary subtype |
| description | string | Description of the collection |
| query | object | Object suitable for passing to collection.find / video.find / user.find that describes the contents in this collection |
| restrictions | integer | 0 = no restrictions 1 = can edit, but not delete 2 = can’t edit or delete |
| count | integer | Number of items in the collection |
options
| limit | integer | Limit the number of results returned to this number - same effect as “LIMIT” keyword in SQL. There is currently a hard maximum limit of 20. |
|---|---|---|
| offset | integer | Skip the first specified number of results - same effect as “OFFSET” keyword in SQL |
| count | boolean | Option of whether to include a count of the total results that would have been returned ignoring the supplied limit/offset. Default is False. |
| orderBy | array (string, boolean) | Return collections ordered by the field specified. If the supplied boolean is True, the results will be in ascending order, otherwise in descending order.
Available sort fields are:
|
returns
If the supplied count option is false, an array of details defined by the returnFields specified is returned for each collection matched. If count is True a tuple is returned: (count, [viddetails, …])
collection.count
Returns number of collections that match the specified query.
collection.count(query)parameters
| query | object | See query object in collection.find |
|---|
returns
Returns the number of items matched by the query
collection.get
This is a shortcut to calling collection.find with a single id. There will always be only one result returned, but it will still be in an array. There are no options for this function.
collection.get(id, returnFields)
parameters
| id | Integer | The id of the collection. All collections have a unique ID, regardless of type. This id may refer to collections of any type |
|---|
returnFields
| The returnFields are the same as those for collection.find. |
errors
| The errors are the same as those for collection.find. |
collection.collect
Has the same effect as calling video.find, user.find, or collection.find according to the collection type, with the query set for this collection.
collection.collect(id, returnFields [,options])parameters
| id | Integer | The id of the collection. All collections have a unique ID, regardless of type. |
|---|
returnFields
| returnFields are based on the type of collection. |
options
| options are based on the type of collection. |
errors
In addition to the global API errors, this function can return the following local errors:
| 1100 | Invalid collection id |
|---|