0

There have been a couple of questions regarding RESTful URL design for searching for resources. What I'm interested in is a RESTful URL for a single resource by something other than the resource ID.

For example, a user has an ID and resource URL /rest/user/<id>. I want to allow searching for a single user by their email address (which is ensured to be unique by the system).

Alternatives I've come up with:

A) /rest/user/email/john.doe@example.com - create a separate resource for accessing the individual resource (though /rest/user/email would be undefined)

B) /rest/user/email:john.doe@example.com - here email:john.doe@example.com is considered an alternative identifier for the user, thus this is the same resource endpoint using an alternative ID

C) /rest/user?email=john.doe@example.com - this is RESTful search, but it would return an array containing zero or one entries, and thus is not a direct reference to the resource

D) /rest/user/search?email=john.doe@example.com - similar search API as (C) but with different semantics

The design should be expandable to searching with different unique IDs provided by the system (an external ID, phone number, SSN, etc).

I'm leaning towards option B, as it defines an alternative way to referencing a particular user (which could be used globally in the service) and reuses existing resource endpoints. This could be expanded to PUT and DELETE as well as GET. But is it very RESTful?

Community
  • 1
  • 1
Sampo
  • 4,308
  • 6
  • 35
  • 51
  • Possible duplicate of [REST API DESIGN - Getting a resource through REST with different parameters but same url pattern](http://stackoverflow.com/questions/20381976/rest-api-design-getting-a-resource-through-rest-with-different-parameters-but) – vtortola Feb 23 '17 at 13:32

1 Answers1

0

/rest/user/search?email=john.doe@example.com, the slash '/' used for represent the level relationship, e.g. /rest/customer/orders/order1, customer has orders collection, orders has a order named order1.

jay liu
  • 129
  • 8