What is a good strategy for adding additional information in a GET query over REST?

Question

Given that we provide a restful api that serves book entities listening at

/books

And a client can get a book at the usual

GET /books/{id}

Suppose that we want to begin offering discounts on books to only our most vigilant buyers. These buyers would be given a discount code, and that code will reduce the price of the book.

Thus, a generic response may be

 GET /books/4
 {"id":4, "price":"24.95"}

Where a response to a query with a discount code may be

 GET /books/4
 {"id":4, "price":"24.95", "yourPrice":"19.95"}

The back-end processing we can get figured out, but what is the best practice for a client submitting a discount code over a restful api?

Certain books will be eligible for discounts while others will not. Discounts will not be broad (20% off everything), but instead will map to a specific price for that particular code (or client/code combo).

We've considered:

• kludging the url

  GET /codes/{someCode}/books/{id}

• Adding the code in a header value

• Using a query string

  GET /books?code=myCode

• anything else?

EDIT: Our goal is not to implement single-use codes. Instead, these discount codes could be used some fixed number of times for some fixed set of books.

Answer 1

I like using query variables. I just looked at the RESTful Web Services book, my main reference in this area, and they say:

Use query variables only to suggest arguments being plugged into an algorithm... If two URIs differ only in their query variables, it implies they're the different sets of inputs into the same underlying algorithm.

It seems to me your discount codes are inputs to a discounting algorithm.

Charles

Answer 2

You can register the code in a table so when the user retrieves that book automatically returns that book with the proper discount, for example:

The user can add some code

POST /register/{code}

This will add an entry to a table {user} - {code} so when the user retrieves by

GET /books/{id}

will use that entry to apply the discount. I'm guessing that you already have some relation between {code}-{book} so wont get into that.

Answer 3

Anything you add in the URL or header values are open to be intercepted, and possibly allowing other users to 'fake' their discount ID. 1 approach would be to introduce a new POST call, that will allow the ID to be encrypted with simple HTTPS. The POSTed data could be as simple as the discountID or customerID.

Added - Sorry Michael, you already said that :)

Answer 4

If you're going to be submitting anything that's not idempotent, I would suggest using POST instead of GET. You wouldn't want a client to be able to use their code more than once.