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