"sticky" filters

[tkellen]

Endpoints allows a server to specify both default includes and default filters for any endpoint.

Our current implementation of filters follows the JSON-API specification's semantics around include. That is, a server can specify a list of default included relations at a given endpoint, but if the user explicitly specifies any in their request, it should completely override the server-defaults. As mentioned above, we are doing the same for filters. However, we are not bound by the specification to do so.

There are times when a server might wish to specify a filter that the user cannot opt out of (such as suppressing records which have been flagged as deleted). While one could argue this should be implemented at the database layer, the general question remains: servers should be able to specify filters that stay by default, and filters which cannot be altered. What should our API for this be?

The current API is this:

controller.read({
  filter: {
    deleted: true
  }
});

Here are three proposed APIs:

controller.read({
  filter: {
    deleted: {
      value: true,
      sticky: true,
      locked: true
    }
  }
});

controller.read({
  filter: {
    deleted: true
  },
  filterSettings: {
    deleted: {
      sticky: true,
      locked: true
    }
  }
});

controller.read({
  filter: {
    deleted: true
  },
  stickyFilters: ['deleted'],
  lockedFilters: ['deleted']
});

I like the first best but it could be a little weird if we ever had a situation where the value of a filter was itself an object, then you'd end up with:

controller.read({
  filter: {
    deleted: {
      value: {
        key: 'pair'
      }
    }
  }
});

I'm struggling to think of a scenario where that would happen, and even if it would, perhaps it is sufficiently rare that this ugly configuration is acceptable?

Thoughts @bobholt?

[tkellen]

It's also just occurred to me that some of this might belong at the model layer (otherwise you'd have to repeatedly set your sticky/locked deleted filter at every controller which could include the relevant resources). Even so, an implementor probably needs the flexibility to control it on a per-endpoint basis?

[bobholt]

Yeah, from a per-endpoint standpoint, maybe I want to make an admin endpoint that can see the deleted records, so it's useful to do it in the model and use the controller for overrides.

I like the first one, too, for its simplicity. The object value is ugly, but I think it will be anyway. Here's another option to throw in the mix, though I still like number 1.

controller.read({
  filter: {
    employee: 12
  },
  stickyFilter: {
    is_active: true
  },
  lockedFilters: {
    deleted: true
  }
});

Granted, I'm not grokking the difference between sticky and locked. Would a filter need to be specified as both?

[tkellen]

Locked means if the server default is, say true for some filter, it's invalid to try to set it to anything else. The endpoint would either throw an error for that request or silently ignore the value.