10

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

eversor
  • 3,031
  • 2
  • 26
  • 46

3 Answers3

11

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

Community
  • 1
  • 1
Thierry Templier
  • 198,364
  • 44
  • 396
  • 360
9

Most certainly this one

GET: /items?attribute={value}

Why?

GET: /items/attribute/{value} is wrong because with REST, url segments represent resources, attribute is not a resource

GET: /items/findByAttribute?attribute={value} is wrong for the same reason really. findByAttribute is not a resource

Using url queries to filter by attributes is perfectly fine, so go with that.

Tim
  • 41,901
  • 18
  • 127
  • 145
  • 1
    URI semantics are irrelevant to REST. An URI is an atomic identifier. If clients are obtaining any information from URI segments, they are doing it wrong. – Pedro Werneck Mar 20 '15 at 04:02
  • I share the sentiment, however, what if the attribute you are filtering on is unique, and you want returned a single resource, as opposed to a collection of resources that match the query params, how would you go about that? Because the GET /items endpoint generally returns an array/collection of items, not a single item. – Adam Reis Jan 19 '23 at 03:16
  • 1
    @AdamReis filtering a collection of items conceptually cannot result in a single item, it should always result in another collection. – Tim Jan 25 '23 at 10:11
6

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.

Pedro Werneck
  • 40,902
  • 7
  • 64
  • 85