Sorting and filtering on accessible fields

Within a collection, a field can be sortable, which means that the collection is ordered based on the values of that field. A field can also be filterable, which means that the collection members can be filtered based on the field's value.

However, with additional accessible fields filters, a sortable or filterable field may not always be available to the caller. For example, suppose an account has four AccountContacts: the insured, the producer, and two additional insureds. Suppose that primaryPhone is sortable and filterable, but it is also restricted so that the producer cannot access primaryPhone for the third-party contacts. Sorting and filtering on primaryPhone could expose information about those values that the caller should not be allowed to see. What happens if the producer attempts to sort or filter on primaryPhone?

The behavior depends upon whether the collection is query-backed or stream-backed.

Query-backed collections

When a collection is query-backed, Cloud API lets you sort and filter on a field only if the field is available to all callers. In other words, every reference to the collection type in every accessiblefields.yaml file must specify that access to the field is always allowed. If access to the field is not granted to all callers, then sorting and filtering is not allowed on that field.

For example, suppose the AccountContacts collection is query-backed and that name and primaryPhone are sortable and filterable. Also, the restricted.accessiblefields.yaml file specifies the following:
accessibleFields:
 ...
 AccountContact:
   edit: []
   view:
   - id
   - name
 ...

name is available to all callers, even to callers with additional accessible field restrictions. Therefore, sorts and filters on name are allowed.

primaryPhone is not available to all callers. Those with additional accessible fields restrictions cannot see this field. Therefore, sorts and filters on primaryPhone are not allowed, even for callers with no additional accessible fields restrictions.

This behavior exists because a query-backed collection is not loaded into memory all at once. Rather, the collection is loaded one page at a time. Cloud API begins to build the response before it has loaded every page of the collection. Cloud API cannot know whether any member of the collection will be restricted by an additional accessible fields filter. Therefore, because there could be a member of the collection that requires restricted access, it cannot allow access to sorting and filtering on that field.

Stream-backed collections

When a collection is stream-backed, Cloud API lets you sort and filter on all sortable and filterable fields. However, if a field on a given resource is restricted to the caller, Cloud API treats the field's value as if it were null for the purpose of sorting and filtering.

For example, suppose the AccountContacts collection is stream-backed and that lastName and primaryPhone are sortable and filterable. Also, the appropriate accessiblefields.yaml file specifies the following:
accessibleFields:
 ...
 AccountContact:
   edit: []
   view:
   - id
   - lastName
 ...

Finally, suppose there are four AccountContacts in a collection:

  • Ray Newton (the insured); primary phone: 111-1111

  • Karen Egerston (the producer); primary phone: 333-3333

  • Sue Thompson (an additional insured); primary phone: 222-2222

  • Virginia Green (an additional insured); primary phone: 444-4444

Aaron Applegate is a billing clerk who is not bound by additional accessible fields filters. If he sorts the collection based on primaryPhone, he will see this:

  1. Ray Newton; primary phone: 111-1111

  2. Sue Thompson; primary phone: 222-2222

  3. Karen Egerston; primary phone: 333-3333

  4. Virginia Green; primary phone: 444-4444

Karen Egerston is a producer who is bound by additional accessible fields filters and cannot view primaryPhone on additional insured contacts. If she sorts the collection based on primary phone, she will see this:

  1. Sue Thompson; primary phone: (null)

  2. Virginia Green; primary phone: (null)

  3. Ray Newton; primary phone: 111-1111

  4. Karen Egerston; primary phone: 333-3333

Note that the Sue Thompson and Virginia Green AccountContacts have been sorted as if their primary phone values were null.

This behavior exists because the entire stream-backed collection is loaded into memory at one time. Thus, Cloud API knows which members of the collection are restricted by an additional accessible fields filter before it starts to build the response. It can permit sorting and filtering on the field, and it simply obfuscates the restricted information by treating it as null.