Pretty new to all this REST stuff.
I’m designing my API, and am not sure what I’m supposed to return from a search query. I was assuming I would just return all objects that match the query in their entirety, but after reading up a bit about HATEOAS I am thinking I should be returning a list of URI’s instead?
I can see that this could help with caching of items, but I’m worried that there will be a lot of overhead generated by the subsequent multiple HTTP requests required to get the actual object info.
Am I misunderstanding? Is it acceptable to return object instances instead or URIs?
IMHO it is important to always remember that “pure REST” and “real world REST” are two quite different beasts.
How are you returning the list of URIs from your query in the first place? If you return e.g.
application/json, this certainly does not tell the client how it is supposed to interpret the content; therefore, the interaction is already being driven by out-of-band information (the client magically already knows where to look for the data it needs) in conflict with HATEOAS.So, to answer your question: I find it quite acceptable to return object instances instead of URIs — but be careful because in the general case this means you are generating all this data without knowing if the client is even going to use it. That’s why you will see a hybrid approach quite often: the object instances are not full objects (i.e. a portion of the information the server has is not returned), but they do contain a unique identifier that allows the client to fetch the full representation of selected objects if it chooses to do so.