Collections & Filters

Due to the nature of the way customers use TextUs, accounts will typically have tens or hundreds of thousands of common objects, like Contacts or Conversations. Because getting a single list of these would not be useful or performant, we have come up with a common set of rules to view a useful subset of each, called Filters.

Filters

A Filter has a name (eg, “Open Conversations”, “Blocked Contacts”, etc), and provides a Collection, which is a paginated subset of all the possible items. Some resources allow the User to perform a search, and then save that search as a custom Filter.

Collections

A Collection is a hydra:Collection and is detailed in the Hydra Specification, 5.1. A Collection that does not implement pagination will always return all the members of the collection in the response, and will always include the members and totalItems attributes.

  • members - This is an Array of items contained within the Collection. If it does not contain the entire set of items, then a “view” will be provided to other “pages” of the collection (see Pagination, below).
  • totalItems - The total number of items contained within the Collection. If the collection is paginated, then this number may be larger than the number of items included in the members Array.

Example 

{
  "@type": "hydra:Collection",
  "id": "/conversations/kY1QwY/timeline",
  "@context": "/contexts/hydra:Collection.jsonld",
  "totalItems": 3,
  "members": [
    {
      "@type": "Message",
      "id": "/messages/QNDkpL",
      "@context": "/contexts/Message.jsonld",
      "direction": "out",
      "body": "Chuck Norris doesn't use web standards as the web will conform to him.",
      "formattedBody": "<div>Chuck Norris doesn't use web standards as the web will conform to him.</div>",
      "displayTimestamp": "2018-07-24T20:59:32.156Z",
      "timelinePosition": "2018-07-24T20:59:32.156Z",
      "deliveryState": "delivered",
      "conversation": "/conversations/kY1QwY",
      "sender": "/users/hikvlD",
      "attachments": {
        "@context": "/contexts/hydra:Collection.jsonld",
        "@type": "hydra:Collection",
        "id": "/messages/joZqVWd/attachments",
        "members": [],
        "totalItems": 0
      },
      "friendlyStateDescription": "Message Delivered",
      "retryAllowed": false,
      "retry": null,
      "latestEventAt": "2018-07-24T20:59:32.156Z",
      "flags": []
    },
    ...
  ]
}

Pagination

Since offset-based pagination results in poor performance and bugs in large collection, we instead use cursor-based pagination for Collections. Every Collection that supports pagination will include a view attribute, which contains links to other pages within the collection:

Example 

{
  "@type": "hydra:Collection",
  "id": "/conversations/kY1QwY/timeline",
  "@context": "/contexts/hydra:Collection.jsonld",
  "totalItems": 3,
  "members": [ ],
  "view": {
    "@context": "/contexts/hydra:PartialCollectionView.jsonld",
    "@type": "hydra:PartialCollectionView",
    "id": "/conversations/kY1QwY/timeline",
    "first": "/conversations/kY1QwY/timeline",
    "next": "/conversations/kY1QwY/timeline?cursor=1oAVVvjkk8MW3tEnJ,
    "previous": null
  }

The view is a hydra:PartialCollectionView.

© 2024 TextUs