CODEWITHSUNDEEP
javarest
Pankaj
Pankaj

Reputation: 3674

url design for RESTful services

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?

Upvotes: 8

Views: 201

Answers (3)

kapex
kapex

Reputation: 29999

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

Upvotes: 0

Welsh
Welsh

Reputation: 5468

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.)

Upvotes: 4

Freedom
Freedom

Reputation: 833

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.

Upvotes: 5

Related Questions