Should you return all resources by default (when no filter specified)

#1

Hi there,

Let’s say I use a soft delete strategy with a status which could be published or trashed.

By default (without specifying a filter) I would like to return all posts which are published.
Is that allowed or should I call /posts?filter[status]=published ?

I would prefer to just get /posts, and have only the published ones, and then get /posts?filter[status]=trashed to get only the trashed ones, or get /posts?filter[status]=all to get everything.

I cannot find an answer to this in the spec.
What do you think?

Thanx

Soft Delete Resources
#2

I would be wary of doing things which are not immediately intuitive to the API consumer. You are under no responsibility to display any resources you don’t want to, but I would make sure you properly convey this behavior to consumers otherwise you will have a lot of confused and annoyed developers on your hands.

Unless you have a solid, very apparent, means to show this (like vocabulary driven hypermedia) and all clients are using a discovery mechanism, I would suggest instead returning some links to the “root” of each filtered set with the filter strategy.

#3

Hi Michael, thanx for getting back to me.

The reason behind this is that 99% of the time, the API should return only resources that are published.
So I believe that /posts by default should return the same thing as /posts?filter[status]=published

I don’t want 99% of the calls to the API to include a filter that could be considered default and thus avoided.

For the 1%, the call could be ?filter[status]=trashed or ?filter[status]=all

I don’t see any problems in doing so but you are right, I have to convey the information to the developers.

But I’m curious, what do you mean by returning some links to the “root” of each filtered set with the filter strategy.

#4

Wow, apologies for dropping the ball on this response. I’m not sure if this will help so long after you’re question but I’ll do it anyway just in case.

GET /posts
200 OK
{
  "links":{
    "published":"http://example.org/posts?filter[status]=published",
    "trashed":"http://example.org/posts?filter[status]=trashed",
    "all":"http://example.org/posts?filter[status]=all"
  }
}