url design for RESTful services

Question

I have a resource called Pricing which i want to retrieve. An Offer can have pricing and a Promo can have Pricing resource and there is another entity Customer with which Pricing can be mapped. I want to retrieve Pricing based on either one of OfferId / PromoId / CustomerId .

To design the URLs for this, i'm running into two options:

Option 1: Pass it as query string

/pricing?OfferId=234&PromoId=345&CustomerId=543234

Option 2: Have three APIs

/pricing/offer?id=234
/pricing/promo?id=345
/pricing/customer?id=543234

IMO, OfferId / PromoId / CustomerId should be treated as attribute of the resource. Therefore pass attribute as query string.I'm more inclined towards Option 1.

Option 2 avoids if else condition to retrieve the resource and looks much cleaner but does it seems to be supporting REST standard of URL design?

What's the REST standard to design the URL. Which option would you recommend?

Answer 1

I prefer the Option 1.
The Option 2 has the following defects:

1. it may confuse users. for instance, /pricing/offer/234 seems to represent an Offer resource, not a Pricing resource.
2. in business logic, an Offer resource contains a Pricing , but /pricing/offer/234 represent right on the contrary way. It seems like a Pricing resource contains an Offer resource.

Actually, the Option 1, has some problems too. for example,

/pricing?OfferId=234&PromoId=345&CustomerId=543234  

will get three Pricings, right? It seems

/pricings?OfferId=234&PromoId=345&CustomerId=543234  

is more reasonable.

Another option you can think about is Option 3:

/offer/234/pricing
/promo/345/pricing
/cusomer/543234/pricing

hope it helpful.

Answer 2

The way that would be most clean and follows standard pathing would be:

/pricing/offer/234
/pricing/promo/345
/pricing/customer/543234

With the layout being: /pricing/${offer|promo|customer|/${PathParamForId}

Which you could then do as three separate methods one each for offer/promo/customer.

Then you just have to make sure your API is well documented so users know the expected behaviors for the paths. (Difference between offer vs promo lookup and etc.)

Answer 3

This is already suggested by @Freedom but I think it deserves its own answer and reasoning.

You want to retrieve a pricing - but that doesn't mean you have to start the URL with it pricing .

Promo , Offer and Customer look like resources. They probably have have their own URLs, like offer/123 . Even if they don't have URLs they still seem to be a logical container/composition element of a Pricing . So a Pricing should be a sub-resource of those.

/offers/234/pricing
/promos/345/pricing
/customers/543234/pricing

If a pricing has its own id too, you can still add an additional way to list all pricings or get them by that ID:

/pricings
/pricings/12