RESTfully Fetching by Attribute

Question

Which of the following URLs is more RESTful compliant when it comes to fetch only items that have a certain value for attribute?

1. GET: /items/attribute/{value}

2. GET: /items/findByAttribute?attribute={value}

3. GET: /items?attribute={value}

Having in mind that GET: /items returns all items.

---

Example

1. GET: /shirts/color/FF9900

2. GET: /shirts/findByColor?color=FF9900

3. GET: /shirts?color=FF9900

Answer 1

I think that the last option is the correct one ;-)

Here are some comments for the others:

• Generally the path element right after the one that corresponds to the list resource is the identifier of the element. So if you use something at this level, it could be considered as an identifier...
• You can have resource to manage a particular field but the URL would be something like /items/{itemid}/fieldname.
• You shouldn't use "action names" within the URL (in your example findByAttribute). The HTTP method should correspond to the "action" itself. See this answer if you want to support several actions for an HTTP method: How to Update a REST Resource Collection.
• There is a question about how to design search filter: How to desing RESTful advanced search/filter. I think that your use case if a bit simple and using query parameters matches for you.

Otherwise I wrote a post about the way to design a Web API. This could be useful for you. See this link: https://templth.wordpress.com/2014/12/15/designing-a-web-api/.

Hope it helps you, Thierry

Answer 2

URI semantics are irrelevant to REST. It doesn't make sense to ask which URI is more RESTful. What makes an URI RESTful or not is how the client obtains it. If he's reading URI patterns in documentation and filling placeholders with values, it's not RESTful. If this is news for you, I recommend reading this.

With that in mind, all three examples can be RESTful if the server provided that URI template to the client as a link to query the collection resource filtering by that value, but 3 is definitely the best option since it follows a more conventional query syntax. I wouldn't use 2 since it implies a method call and it looks too RPC for my taste, and I wouldn't use 1 since it implies for a human that it will return only the attribute as a resource.