The point of an interface is to hide the fact that there are different possible implementations. When you sit in a restaurant, basically you care only that you’ll get service from someone. You may or may not be aware that you might get service from Jose, Marcia, or Stephanie, and you definitely don’t want to have to do different things in order to get the same cheeseburger from different waiters. Your view of the transaction as a consumer is “get a cheeseburger”, not “talk to Jose”/”talk to Marcia”/”talk to Stephanie”.

If the consumer has to know about all the possible implementations, and which one he wants to access, then for purposes of your API you might just as well not have an interface, since you’re not actually saving the effort that it’s supposed to save. It can still be useful to make details of the implementation easier, but as long as the difference between the alternative object classes is externally visible, the interface ceases to be a useful API component.

I assume all the fruits, apples, oranges, and so one, all have fruit ids. So if you want to reference a specific fruit in a basket, then:

/baskets/{basketId}/fruits/{fruitId)

is still valid. However, if the “fruitId” is unique, it would me much better to just use

/fruits/{fruitId)

However, if you only want to see certain types of fruits in a basket, then you can take advantage of the query string in it’s role of “narrowing” the resource:

baskets/{basketId}?fruits=mango

or

baskets/{basketId}?fruits=apple&fruits=banana

Once you get that list of items, each should have it’s own ID & you can get them individually if you like.

From a RESTful point of view, there are two resources here:

• a collection of the fruits in a given basket

• an individual fruit

Use the query string to limit the collection resource, and use the (shorter) fruitId once you know which specific one you want.

BTW The problem remains the same if you are selecting fruits from someone’s hat:

/hat/{hatId}?fruits=bananas&fruits=pineapples

EDIT: (taken from comments so it will be more readable)

To add an apple

POST /basket/{id}

(the apple representation)

POST is often considered the “append” verb, but you could use PUT. Note that you’re appending the apple to the basket collection, so you use the collection URI.

To find the apples in the basket:

GET /basket/{id}?fruits=apple

EDIT EDIT: If you have some other code/value/attribute in mind, just support that in the query string:

GET /basket/{id}?color=red

The most RESTful way would probably be to define separate routes for each fruit type:

baskets/{basketId}/apples
baskets/{basketId}/apples/{appleId}
baskets/{basketId}/bananas
baskets/{basketId}/bananas/{fruitId}
... other fruits

And use a different media type for each fruit, e.g.:

application/vnd.com.example.apple+json
application/vnd.com.example.banana+json

In this case you would need to request a list of every possible type and handle them individually.

A less RESTful solution might be to treat fruit as the interface that it sounds like it is, and just get a list of them.

baskets/{basketId}/fruits
baskets/{basketId}/fruits/{fruitId}

Since JSON is usually schema-less, each item can look completely different, and you could use some identifying characteristic to map each to the specific fruit class which understands its JSON representation and contains its behavior.