CODEWITHSUNDEEP
rest
tomturton
tomturton

Reputation: 1368

Does RESTful practice define the extent of data to return, when no ID is included?

I am designing a REST API for my service and am trying to decide how much data should be returned about a resource, when an ID isn't specified, For example purposes, let's pretend the API is for a library.

While I am happy for GET library/books/283765 to return all the information about this specific book, I am less certain on what GET library/books should return.

At a minimum I would expect to see a complete list of book IDs. I might be tempted to accompany each ID with the book's title, maybe also the author. As I know this is a large library, I would be surprised to see all the information about every single book (Publisher, Year, ISBN, Blurb etc). Is this something REST has an opinion about?

If not, would it be bad design when describing another set of resources, to return more or less data?

Lets pretend GET library/rooms lists IDs for all the rooms in the library. But in this case, the only property a room has is Name. If GET library/books only returns book IDs, then surely I should follow the same rule for GET library/rooms, even if it seems inefficient in this case.

Perhaps the answer is return the minimum amount of data about each resource, that a user might want to know? This would potentially prevent thousands of GET requests, or one extremely large one. The hard thing of course is trying to decide what the minimum amount of data actually is.

Any thoughts?

Upvotes: 1

Views: 473

Answers (2)

Eric Stein
Eric Stein

Reputation: 13682

Is this something REST has an opinion about?

REST has no opinions on how URLs should be formulated.

If not, would it be bad design when describing another set of resources, to return more or less data?

It is expected that different resource collections will have different detail levels of data available by default.

Perhaps the answer is return the minimum amount of data about each resource, that a user might want to know?

That is the goal. More specifically, the appropriate amount of data for somebody looking at the collection. Users seeking more detail will have to follow the URL to the individual resource (book, room, etc) to learn details like print run number or floor color.

You as the developer have to pick the set of default information for each collection endpoint. Check with some potential end users and see what they expect. At a minimum, probably a link to the item, id, title, and author for a book, but it really depends on what your users intend to do with it. Perhaps you're writing a system for librarians, in which case the Dewey Decimal number might be top-level information.

Upvotes: 2

ericpap
ericpap

Reputation: 2937

I have not experience with Rest services, but i think as a general rule, you should return what the user really need in most of the cases. In case some user need extra data about a book should query que service for the specific book ID to get it.

If you think that your database will be too big for sending for instance a colection of books, you got other options, like asyncronic returns or paginate the service result. In the last case the service will return only 100 books per page. So if the book the user is searching is not in the list, he will ask for the next page.

Also i would advice you to force at least one filter to narrow down the list of books. Think that is not logical from the user point of view to navigate a list of say 10000 books for a specific one. Hope it helps you.

Upvotes: 0

Related Questions