125

I'm trying to design a RESTful API where the users can fetch a single product or list of products in a single GET request. Each product has a unique id.

The single product URL is simple enough:

http://mycompany.com/api/v1/product/id

This returns the information for a single product. I'm confused as to how the URL for multiple product information should look like.

How about

http://mycompany.com/api/v1/product/ids

where ids is a comma separated list of ids?

Improve this question
3
  • 2
    id use something like http ://mycompany.com/api/v1/getproducts?ids=[listofids] Commented Feb 21, 2012 at 2:20
  • 2
    How is a question about API design duplicate of a question about implementation details in Rails? Commented Apr 2, 2013 at 10:51
  • 1
    /getproducts... is RPC style, not REST Commented Jan 18, 2022 at 21:25

2 Answers 2

Reset to default
215

I would recommend thinking of it like you are listing multiple representations of the resource filtered by id. As such you make a GET request to the base resource:

https://example.com/api/v1/products

And filter the response list by id:

https://example.com/api/v1/products?id=1,2,3

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

13 Comments

This is the superior answer imho, reason being: /products and products?id=1,2,3 will give consistent responses (=collection resources). Comparing /products/1 and /products/1,2,3 is a recipe for client headaches - unless of course all nested endpoints return collections by default (which is also an interesting approach, for an example see the api+json format)
I like this approach, but shouldn't it be example.com/api/v1/products?id=1&id=2&id=3 ?
@Nitek No; there is no guarantee that duplicate query parameters will be combined into an array. For your example URL, PHP would indeed tell you that id equals [1, 2, 3], but Ruby on Rails would tell you it equals 3, and other frameworks may also act differently, e.g. saying id equals 1.
I would expect products?id= to return no results and products to return all results.
@ma11hew28 because id is the field on the object being matched against.
|
73

Your suggestion of ids separated with commas is good enough.

It would be instructive to examine some public REST APIs to see how they handle. For ex, the StackExchange API separates ids with a semi-colon - https://api.stackexchange.com/docs/answers-by-ids

Improve this answer

5 Comments

I wonder why people don't use products?id[]=1&id[]=2. URL parsers handle this just fine.
@JulioGreff I think, it's because it just looks a bit ugly. No other particular reason.
@JulioGreff RESTful api's don't just select by id, they also decorate. example /api/dogs/fluffy1234 could be extended to do more things like this: /api/dogs/fluffy1234/siblings and so, if you can keep the selector logic in the same place where the ID would normally go, then you can still use your decorators
This is the example, api.stackexchange.com/2.2/answers/…
Performance can also be better with a series of "GET product" requests because the server's response time for an aggregated query is NEVER faster than the lookup of the product that takes LONGEST to return. Plus, you cannot indicate "some items not found" as a response code, which usually leads to dirty workarounds like usage of WebDAV's HTTP 207

Start asking to get answers

Find the answer to your question by asking.

Ask question

Explore related questions

See similar questions with these tags.