CODEWITHSUNDEEP
apirest
Lodewijk
Lodewijk

Reputation: 2391

Rest Resource always by Id?

In a RESTfull API, what is the best way to represent a filtering of a resource? Most examples speak of an URL that is structured /resouce/9/subresource/5. I wish to represent a filtered list of a resource like this: /resource/9/subresource/validated. This validated property is a top-level concept in the domain of the API.

Is this considered 'okay' in a restfull api? Moving the validated to the querystring feels like it diminishes the importance of the concept.

Edit

Let me try to explain my question with a concrete example: The api of stackexchange has the following resource: /users/{id}/notifications/unread. One could argue that the list of unread notifications can be considered a resource on its own.

Upvotes: 0

Views: 89

Answers (1)

Augusto
Augusto

Reputation: 29877

If you want a purist REST API, remember that each resource type is represented by the same url, so something like /resouce/9/subresource/5 should return something very different than /resource/9/subresource/validated.

Most APIs I know use query parameters to get a subset of the resources (for example, for filtering, pagination, etc). In you case the urls would be something like /resource/9/subresource?validated=true

Some APIs follow a different approach and had specific urls that work as filters (as your /validated example). The reason behind this is usually that there's a perception that there could be quite a lot of complexity on the API... which is the case if it's not designed properly. Imagine in the case that some parameters only work when other parameters are set, for example that pagination works if you query the whole collection, but not if you want only the validated resources, mixed with poor documentation)

About moving the validated to the query string.. can you clarify why it would diminish the concept of validated? As on REST API the resource is king, rather than a property of the resource.

(note: I have no idea how you use backslashes on your urls)

Edit

Trying to answer your comment as I think this is important! :).

If those URLs return a list that contain the same resource, let's say a user, then validated, removed, foobared, etc are states of the user, while user is the resource.

I had similar doubts when I started building REST APIs, and it does require mind shift. The URLs have to represent resources, and not state or operations/commands.

Edit 2

Ok, that explains the confusion. The Stack Exchange API is ... not really a REST API (the word REST is not even mentioned on that page). It's more a RPC over HTTP, which uses JSON as the representation.

To clarify the above statement (and before I get kicked out of the site ;). REST is usually explained as having 4 levels, which you can read on this blog post Haters gonna HATEOAS. I'm copying here the one of the relevant bits regarding the levels of conformity to REST.

  1. “The Swamp of POX.” You’re using HTTP to make RPC calls. HTTP is only really used as a tunnel.
  2. Resources. Rather than making every call to a service endpoint, you have multiple endpoints that are used to represent resources, and you’re talking to them. This is the very beginnings of supporting REST.
  3. HTTP Verbs. This is the level that something like Rails gives you out of the box: You interact with these Resources using HTTP verbs, rather than always using POST.
  4. Hypermedia Controls. HATEOAS. You’re 100% REST compliant.

The StackExchange API is at most at level 2 (level 1 would be 1 endpoint using something like SOAP). Personally, I only recognise an API as 'REST' if it uses at least HTTP verbs, otherwise it is still RPC over HTTP, but with the only distinction that you have several endpoints.

So maybe the question for you is: What level of REST do you want to implement in your API? A word of caution here, going full HATEOAS might sound really cool, but it will increase the complexity of your application... so you have to ask yourself if you're ok with paying for that extra complexity (e.g. autodiscovery of new operations).

And really important, build the API that you think will be the easiest to use for your clients. It's better to take a practical approach to REST rather than a religious one, and as an example, here are the US White House REST standards. Give that a read, I really agree on most, if not all, of the practices in there.

Upvotes: 3

Related Questions