Filter

• Filter fields
• Filter Clauses
• Filter variables
• JSON Pointer

A Filter restricts a stream of messages on the server side so your client only sees what it’s interested in. Streams are currently the only way to use filters right now.

{
  "clauses": [
    {
      "field": "/data/entities/hashtags/*/name",
      "object_type": "post",
      "operator": "matches",
      "value": "rollout"
    }
  ],
  "id": "1",
  "match_policy": "include_any",
  "name": "Posts about rollouts",
  "owner": "...user object..."
}

Filter fields

Field	Type	Description
id	string	Primary identifier for a filter. This will be an integer, but it is always expressed as a string to avoid limitations with the way JavaScript integers are expressed.
name	string	An optional User assigned name for this filter.
clauses	list	A list of filter clauses to match against. Must be non-empty.
match_policy	string	How should the clauses be joined together? One of include_any, include_all, exclude_any, or exclude_all. For example, include_any will include a message if it matches any of the clauses and exclude_all will exclude a message if it matches all of the clauses. This allows either white- or blacklist filtering.
owner	User object	This is an embedded version of the User object. In certain cases (e.g., when a user account has been deleted), this key may be omitted.

Filter Clauses

Field	Type	Description
object_type	string	What type of object does this filter operate on? Must be one of post, star, user_follow, mute, block, stream_marker, message, channel, channel_subscription, token, file.
operator	string	How should field be matched against value. Operator Description equals Does field equal value. matches Is the string value a substring of field. lt Is the integer in field < value. le Is the integer in field ≤ value. gt Is the integer in field > value. ge Is the integer in field ≥ value. one_of Is the field an element in the list value.
field	string	A JSON Pointer string that specifies what part of the message we should match against.
value	string, int, or list	A string, integer, or list that the message's data is compared against. Some variables are also accepted.

Filter variables

Value	Type	Description
$authorized_userids	list	A list of the current user ids who have authorized the App that is using this filter in a stream. Since this is a list, make sure you use the one_of operator with this variable.

JSON Pointer

We use a slightly modified version of the JSON Pointer standard to specify which part of a message we should filter against. According to the spec:

JSON Pointer defines a string syntax for identifying a specific value within a JSON document.

For instance, in the message:

{
  "data": {
    "canonical_url": "https://alpha.app.net/adn/post/914440",
    "created_at": "2012-10-11T19:48:40Z",
    "entities": {
      "hashtags": [
        {
          "len": 8,
          "name": "adnhack",
          "pos": 90
        }
      ],
      "links": [
        {
          "len": 29,
          "pos": 100,
          "text": "http://appnet.eventbrite.com/",
          "url": "http://appnet.eventbrite.com/"
        }
      ],
      "mentions": [

      ]
    },
    "html": "<span itemscope=\"https://app.net/schemas/Post\">If you're in San Francisco on Saturday October 20 and Sunday October 21 come to the first <span data-hashtag-name=\"adnhack\" itemprop=\"hashtag\">#adnhack</span> => <a href=\"http://appnet.eventbrite.com/\">http://appnet.eventbrite.com/</a></span>",
    "id": "914440",
    "machine_only": false,
    "num_replies": 1,
    "num_reposts": 3,
    "num_stars": 3,
    "source": {
      "client_id": "caYWDBvjwt2e9HWMm6qyKS6KcATHUkzQ",
      "link": "https://alpha.app.net",
      "name": "Alpha"
    },
    "text": "If you're in San Francisco on Saturday October 20 and Sunday October 21 come to the first #adnhack => http://appnet.eventbrite.com/",
    "thread_id": "914440",
    "user": "...user object...",
    "you_reposted": false,
    "you_starred": false
  },
  "meta": {
    "code": 200
  }
}

• /data/source/client_id = “caYWDBvjwt2e9HWMm6qyKS6KcATHUkzQ”
• /data/entities/hashtags/0/name = “adnhack”
• /data/num_replies = 1

We extend JSON pointer slightly to allow all the elements of a list to match. For example, to answer the question “Does this post contain the hashtag ‘rollout’”, you’d use a field selector like /data/entities/hashtags/*/name. Following the JSON Pointer spec, if you’d like to encode a literal * you can use ~2 instead.