Improve documentation on filters

[miguelsan]

I have read the docs and done an above review of filters and still don't really understand their effect, or what do they offer that cannot be achieved through the usage of fetchable_fields and finders. I'd like somebody to shed more light on this.

[lgebhardt]

The filters allow you to restrict the resources returned (think search), whereas the field sets and fetchable_fields control what data is returned for each resource (think fewer fields). So if you want to allow someone to find people with the last name of Smith you would need to allow a filter on last_name. Then a request could pass in a filter for last_name, for example http://example.com/people?filter[last_name]=Smith. The system will find all people where the last name exactly matches Smith.

In your resource you define the available filters (fields you wish to allow searching on). Then in GET requests the find method is called, which applies and provided filters using the apply_filter. If you wish to override the way a resource interprets a filter you can override the apply_filter method, and there's an example in the readme. you might need to do this if you want a case insensitive search, or a partial word search.

You can probably ignore the finder methods. They were important in the early releases of jsonapi-resources, but now you can accomplish most customizations in other ways, such as the apply_filter method. I should probably deemphasize them the docs.

[miguelsan]

Ah, so you are talking about filter in the sense of the spec. It'd be easier to understand if you point this out in the README with a small URL example.

On the finders, they are useful in case of "server filtering", which is another story. Imagine some hidden attributes on a resource like user_id, you may want to restrict all responses to the current user. Don't remove them absolutely, because they are the only way to achieve this now.

[lgebhardt]

@miguelsan, Actually you can limit the response globally with the records method. The options are passed to records, so you can use those to limit records to the current user if you include that by way of the context. You could also put some default filters on with the records method override.

I'll see if I can give the documentation a fresh look along with the changes needed to support the JSONAPI RC2 release.

[miguelsan]

I know that records is employed to scope the finders (maybe scope would be a better naming for that method?).

But how would it look like with the filters? I am not sure that I want a filter for an attribute that I am not returning afterwards since I hide it under fetchable_attributes. Would it clash or produce weird behavior?

[lgebhardt]

The filtering would take place separately from the fields. Active record allows you to filter on fields that are not part of the result set so things should work fine (not that we're currently limiting the result set to just the selected fields, but we should). As to wether it's desirable to do things this way I'm not sure. I guess it would depend on the situation. I can see some cases where it would even make sense to filter based on a related resource that's never part of the result set.

I'm not sure on the scope name. It could work, but I'll need to think about it.

[barelyknown]

I'm very 👎 on changing the records method name. It's public and typically overridden - no need for a breaking change.

[miguelsan]

@barelyknown It needn't be a breaking change: make an alias, change docs, and eventually return a deprecation warning. The question is mainly if it makes sense in itself, since it is already a railish convention. I just suggest it to be evaluated and tend personally to favor it slightly, despite I wouldn't dare to advocate it myself.

[vrybas]

@miguelsan the docs for filters are pretty good now. Should be closed?

[miguelsan]

Hey, it is for sure a nice improvement and it might be regarded as good enough. Nonetheless, I have proposed my own changes under #639. Somebody may want ot merge them?