I have to put a (read-only) REST service atop of an existing product database. The easy part is having a top level product resource, like:
The first question that comes up here is if I should return full products here or URIs to their individual resources on /api/products/ [...] the con would be that this would cause a caching headache on the /api/stores/1234/retail/products URI.
I would definitely return the full products - imagine the amount the client would have to do if it would simply want to display a list of product names. Ideally this endpoint would be paginated (query string can include something like
&pageSize=10&pageNumber=2, for example).
Also there are various caching solutions around this - for example you can cache all the products in a data structure service like Redis.
To complicate things, those products of course also have prices [...] and details subresource.
Looking at the Richardson Maturity Model level 3, this would be where links come into play, and you could have something like this under a product resource:
<link rel = "/linkrels/products/ABCD/prices" uri = "/products/ABCD/prices?store=1234&process=retail"/>
and another similar link for the product details resource.
@Roman is right, REST is meant to be discoverable, clients should simply follow links (that can have long/ugly uris), instead of having to memorize them (like in SOAP, for example).