API Objects

Collection Updates

Collection Updates modify the contents of a Collection.

The Update Objects

All operations are performed via the graph/collection/mhid/update endpoint.

Modifying operations are performed using an operation object, which takes different arguments depending on the operation type. A list of operations can be submitted at once, with the order of execution being dependent on an order field. Along with a list of operations, an allowDuplicates boolean can be sent back, denoting whether or not this Collection should support duplicate contents. If allowDuplicates is false, and you send back a prepend,append,or add operation, duplicate elements will be removed from the existing Collection prior to the new elements being added.

The following is an example of a complete request body to make a prepend update with allowDuplicates set to false:

We've used single characters in place of actual MHIDs to simplify the following example.

Copy
JSON
// Beginning with
["A","B","C","D","E","F","G"]


// We execute the request with body:
{
  "operations": [
    {
      "operation": "prepend",
      "order": 0,
      "ids": ["E","F"]
    }
  ],
  "allowDuplicates": false
}


// We end with
["E","F","A","B","C","D","G"]

Operation Types

OperationDescription
renameUpdates the name or description of the Collection (see Rename).
prependAdds items to the beginning of the Collection (see Prepend).
appendAdds items to the end of the Collection (see Append).
addInserts items into the Collection at a given index (see Add).
removeRemoves items from the Collection (see Remove).
removeAllRemoves all items from the Collection (see RemoveAll).

Rename

Renames the name or description field of the Collection:

Copy
JSON
{
  "operation": "rename",
  "order": Integer,
  "property": "name" | "description",
  "value": String
}

Property Summary

PropertyDescription
operationThe type of operation. In this case, "rename."
orderAn Integer to indicate the order of execution of this operation, relative to others.
propertyOne of either name or description to indicate the field being updated.
valueThe created date of the Collection in Unix time.

Prepend

Add one or more items to the beginning of the Collection. Items will be added in the order they are sent:

Copy
JSON
{
  "operation": "prepend",
  "order": Integer,
  "ids": [String]
}

Property Summary

PropertyDescription
operationThe type of the operation. In this case, "prepend."
orderAn Integer to indicate the order of execution of this operation, relative to others.
idsAn array of one or more String MHIDs.

Append

Add one or more items to the end of the Collection. Items will be added in the order they are sent:

Copy
JSON
{
  "operation": "append",
  "order": Integer,
  "ids": [String]
}

Property Summary

PropertyDescription
operationThe type of the operation. In this case, "append."
orderAn Integer to indicate the order of execution of this operation, relative to others.
idsAn array of one or more String MHIDs.

Add

Add one or more items to the index position in the Collection. Items are added in the order they are received. If the index is greater than or equal to the size of the Collection, or less than zero, the request will return an error.

Copy
JSON
{
  "operation": "add",
  "order": Integer,
  "ids": [String],
  "index": Integer
}

Property Summary

PropertyDescription
operationThe type of the operation. In this case, "add."
orderAn Integer to indicate the order of execution of this operation, relative to others.
idsAn array of one or more String MHIDs.
indexThe zero-based position in the array to begin insertion of the given ids.

The following is an example of the function of an add operation:

Copy
JSON
// Beginning with:
["A","B","C","D"]

// We execute the request with body:
{
  "operations": [
    {
      "operation": "add",
      "order": 0,
      "ids": ["Y","Z"],
      "index": 2
    }
  ],
  "allowDuplicates": true
}

// We end with:
["A","B","Y","Z","C","D"]

Remove

Remove can operate in one of two ways to remove one or more items from a Collection: By indices, or by ids (but not both types).

Remove by Indices

With the indices field, an index is used for removal since duplicates may be allowed. If an included index is greater than or equal to the size of the Collection, or less than zero, the request will return an error.

Copy
JSON
{
  "operation": "remove",
  "order": Integer,
  "indices": [Integer]
}

Property Summary

PropertyDescription
operationThe type of the operation. In this case, "remove."
orderAn Integer to indicate the order of execution of this operation, relative to others.
indicesThe indices of the items to be removed.

The following is an example of the function of a remove operation, using the indices field:

Copy
JSON
// Beginning with:
["A","B","C","D","E"]

// We execute the request with body:
{
  "operations": [
    {
      "operation": "remove",
      "order": 0,
      "indices": [0,3]
    }
  ],
  "allowDuplicates": true
}

// We end with:
["B","C","E"]

Remove by IDs

With the ids field, ALL instances of the the ID in the Collection will be removed. This is a convenience method when your application does not manage duplicates, and saves the client the hassle of having to first locate the index of the object in the Collection prior to making the remove update.

Copy
JSON
{
  "operation": "remove",
  "order": Integer,
  "ids": [String]
}

Property Summary

PropertyDescription
operationThe type of the operation. In this case, "remove."
orderAn Integer to indicate the order of execution of this operation, relative to others.
indicesThe ID or IDs to be completely removed from the Collection.

The following is an example of the function of a remove operation, using the ids field:

Copy
JSON
// Beginning with:
["A","B","C","D","E","A","F"]

// We execute the request with body:
{
  "operations": [
    {
      "operation": "remove",
      "order": 0,
      "ids": ["A","F"]
    }
  ],
  "allowDuplicates": true
}

// We end with:
["B","C","D","E"]

RemoveAll

Remove all the items from a Collection. The result will be an empty Collection:

Copy
JSON
{
  "operation": "removeAll",
  "order": Integer,
}

Property Summary

PropertyDescription
operationThe type of the operation. In this case, "removeAll."
orderAn Integer to indicate the order of execution of this operation, relative to others.