How to define REST URIs for a resource?

Question

Lets say I have a collection of applicants that can be accessed via

/applicants

An applicant can be uniquely identified two different ways: by ssn or by an id number.

How would I specify my GETs for a specific applicant?

Typically for unique identifiers I would do

/applicants/{id}

but in this case I have two different unique identifiers. Any suggestions on the proper way of handling this.

It seems incorrect to do something like

/applicants/{id} /applicants/ssn/{ssn}

Rob Hruska · Accepted Answer · 2012-01-19 16:51:02Z

3

Being unique and being an identifier are two different concepts. The identifier (i.e. id) would be more appropriate for identifying and locating the resource via URI, because:

You are (probably) in complete control of the id and its lifecycle.
While SSN may be unique today, the government could change the way SSNs work tomorrow. I myself don't like coupling my internal identifiers to external sources.

To me, SSN seems like more a queryable property than a resource identifier, e.g.:

# Searches for applicants with the provided ssn GET /applicants?ssn=000-00-0000

answered Jan 19, 2012 at 16:51

Rob Hruska

121k32 gold badges170 silver badges193 bronze badges

Sign up to request clarification or add additional context in comments.

4 Comments

Mike Over a year ago

Would you consider it to still be appropriate to return a 404 when using a queryable property?

Rob Hruska Over a year ago

Depends on what your /applicants normally responds with. Normally I'd expect it to respond with something like a list of application resources that matched the query string, and if there were no matches, just an empty list. I wouldn't expect it to return a 404 in this case.

Mike Over a year ago

Ok thanks. /applicants normally does return an empty list. But in the case of ?ssn= I think I will return the 404. For ?lastName= or other non-unique identifiers I think I will go with the empty list. Thanks for the input. :D

Rob Hruska Over a year ago

@Mike - I'd advise against that - by returning a 404 you're saying that the /applicants resource wasn't found, but in actuality it still does exist. Some clients may see that as an indication that they shouldn't make further queries to the resource, or that they have a bug. Plus, conditionally returning a 404 vs. a list depending on the query parameters makes it difficult for clients to code to the API, since it's inconsistent. I'd just make your clients search for the SSN and if the list is empty, do what they'd normally do if it wasn't found.

Collectives™ on Stack Overflow

How to define REST URIs for a resource?

1 Answer 1

4 Comments

Hot Network Questions

Collectives™ on Stack Overflow

1 Answer 1

4 Comments

Related