Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

I have been wondering if, rather than a more traditional layout like this:

api/Products
GET // gets product(s) by id
PUT // updates product(s) by id
DELETE // deletes (product(s) by id
POST // creates product(s)

Would it be more useful to have a singular and a plural, for example:

api/Product
GET // gets a product by id
PUT // updates a product by id
DELETE // deletes a product by id
POST // creates a product

api/Products
GET // gets a collection of products by id
PUT // updates a collection of products by id
DELETE // deletes a collection of products (not the products themselves)
POST // creates a collection of products based on filter parameters passed

So, to create a collection of products you might do:

POST api/Products {data: filters} // returns api/Products/<id>

And then, to reference it, you might do:

GET api/Products/<id> // returns array of products

In my opinion, the main advantage of doing things this way is that it allows for easy caching of collections of products. One might, for example, put a lifetime of an hour on collections of products, thus drastically reducing the calls on a server. Of course, I currently only see the good side of doing things this way, what's the downside?

share|improve this question
add comment

2 Answers

up vote 6 down vote accepted

Often when a collection is going to be the most useful way of interacting with your api, it can be simpler to just think of a single as a collection with only one member. Then if later you want to expose an API for interacting with singles, it merely needs to under the covers convert the single passed in to a collection with that member and then it uses the identical implementation of the other API.

I guess what I'm saying here is, if you want collections to be an interaction mechanism, start with the collection only API and after the system is complete, the other API is a simple ancillary attatchment at the interface layer you can add then if you find it particularly useful. You may however find it's usefulness is minimal enough to apply YAGNI and just use the collections interface for the few instances of singles you want.

share|improve this answer
    
While I agree with your sentiment, assuming that we use the example above, given that POST api/Products would be used for passing collection filter parameters and not data for the creation of new products, what would be a reasonable way to create a new product without api/Product? –  Evan Oct 25 '12 at 0:04
    
@Evan Why can't post to api/Products insert multiple (or a collection of one) Products? That seems the most logical to me. Perhaps post Products/Filter for creating filters, or get if they're a retrieval and not creational task. –  Jimmy Hoffa Oct 25 '12 at 0:44
    
Thanks for the elaboration, Jimmy. The reason I didn't see it this way was that I was considering, in the above example, the collection as an identified resource in and of itself. On a backend, api/Product might be "Product" and api/Products thus "ProductCollection". However, after some consideration, I think it may just be better to abstract that all away from the API, as in your suggestion... now to the real question, did you drive away from that truckstop on your way to Thailand, or leave in the boot of a car? –  Evan Oct 25 '12 at 1:13
    
@Evan I'll give you two hints: Seagulls. –  Jimmy Hoffa Oct 25 '12 at 1:41
add comment

The downside is that the calling program also has to pluralize the resource name, which can be tricky for those client languages which don't have built-in pluralization mechanisms. If you leave it singular, it's easier for the caller to automate code generation for his or her client library.

If you want to mitigate this, you can generate the SDKs for your REST service yourself. Or, you can just be opinionated and deal with the complaining :)

share|improve this answer
add comment

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.