URL format for fetching entities by ID

[woemler]

There are multiple ways to fetch instances of entities with a REST web service, we should probably decide on a single one that best supports our potential use-cases. Here are a couple options:

# Fetches Sample record with ID 123, returns 404 if not found
http://api.oncoblocks.org/v1/samples/123

# Fetches Sample record with ID 123, returns an empty set if not found
http://api.oncoblocks.org/v1/samples?samplesId=123

There are pros and cons to both, but I am leaning towards the second option, which could support queries like this:

# Fetches Sample records with ID 123, 456, and 789
http://api.oncoblocks.org/v1/samples?sampleId=123,456,789

Thoughts?

[woemler]

Having thought more about this, I think both should be supported in different instances. For example:

# Good test that sample 123 exists, returns a 404 otherwise
http://api.oncoblocks.org/samples/123

# Good for fetching batch records, where sample records may or may not exist, will return an empty set if none of them exist
http://api.oncoblocks.org/samples?id=123,456,789

[hackersaga]

Hello @woemler ,
Even the first one can serve both the purposes.
For example:

http://api.oncoblocks.org/samples/123,124

can also accommodate multiple ids and is also a correct way.
Source: http://bit.ly/1AG1JdC

I personally prefer the first one because it is more universal and consistent than later one.

[woemler]

@sagarpatidar Thanks for the response and the link. This is a clever idea, I have never seen this URI syntax before. It makes sense though, since presumably a request of http://api.oncoblocks.org/samples/123,456 would not be used in conjunction with other query string parameters.

[hackersaga]

Yeah, It's just that parameter having multiple values should be used at the end of url and rest can be used earlier. In some cases one might need to post multiple ids, each with multiple value. In that case posting json object/string as post parameter can be helpful, though it wouldn't been shown in the url. Generally, we expose those parameters in urls which we want user to see or we want to associate a unique resource to it.

Off the topic, can you please share your email id? I wanted to discuss more about "Scalable genomic data warehouse" project.