what's the difference between a collection and a store in REST?

Question

I'm trying to wrap my head around the difference between a "collection" and a "store" in REST. From what I've read so far,

a collection is:

 "a server-managed directory of resources"

and a store is a:

 "client-managed resource repository"

I found this post: How "store" REST archetype isn't creating a new resource and a new URI?

but it didn't really help me clarify the difference. I mean, I understand one is controlled by the server and the other by the client... but can someone give me a concrete example of what a store might be in a real world application?

I *think it's something like this:

GET http://myrestapplication.com/widgets/{widget_id} -- retrieves a widget from db
POST http://myrestapplication.com/widgets/{widget_id} -- creates a new widget from db
PUT http://myrestapplication.com/widgets/{widget_id},[list of updated parms & their vals] -- update widget
PUT http://myrestapplication.com/users/johndoe/mywishlist/{widget_id} -- updates john doe's profile to add a widget that already exists in the database... but links to it as his favorite one or one that he wants to buy

Is this correct? if so, could the last PUT also be expressed as a POST somehow?

EDIT 1

I found an online link to the book i'm reading... where it makes the distinction between the two:

https://books.google.ca/books?id=4lZcsRwXo6MC&pg=PA16&lpg=PA16&dq=A+store+is+a+client-managed+resource+repository.+A+store+resource+lets+an+API+client:+put+resources+in,+get+them+back+out,+and+decide+when+to+delete+them&source=bl&ots=F4CkbFkweL&sig=H6eKZMPR_jQdeBZkBL1h6hVkK_E&hl=en&sa=X&ei=BB-vVJX6HYWvyQTByYHIAg&ved=0CB0Q6AEwAA#v=onepage&q=A%20store%20is%20a%20client-managed%20resource%20repository.%20A%20store%20resource%20lets%20an%20API%20client%3A%20put%20resources%20in%2C%20get%20them%20back%20out%2C%20and%20decide%20when%20to%20delete%20them&f=false

Area

Neither of those terms are associated with REST. Can you provide references for your quotes? The post you reference is discussing a specific book's (incorrect) interpretation of REST. – Tollhouse

@EngineerDollery interesting comment you make. I am quoting O'Reilly's REST API Design Rulebook, page 15. I've updated my post with a link to the book. Please see "EDIT 1" – Area

Answer 1

REST uses http verbs to manipulate resources. Full-Stop. That's it. To build some classes of browser-based application developers sometimes use local storage (a store), but that has absolutely nothing to do with REST (in fact, it's the opposite). Collections are a special consideration in REST-based API design because the REST principles place considerable constraints on how they are represented in the results of your queries -- special consideration also because there are no standards on how these things should be represented and access if you're using anything other than html as a resource type.

---

Edit: REST suggests that when we ask for a resource we receive that resource and only that resource and that things referenced by that resource are returned as links, not as data. This mimics the http standard by which we return the requested page and links to other pages rather than embedding linked pages. So, our resources should return links to related resources, not the resources themselves.

So, what about collections?

Let's use as an example a college management system that has Course objects each of which contains a huge lists of Students.

When I GET the course I don't want to have the collection of students returned as an embedded list, because that could be huge and because my user might not be interested. Instead, I want to know that the course has a students collection and I want to be able to query that collection separately (when I need to) and I want to be able to page it on demand. For this to work, the course needs to link to the students collection URL (maybe with an appropriate type so that my code knows how to handle the link). Then, I want to use the given collection's url to request a paged list of resources. In this example, the collection's url could be something like: course/1/students, with the convention that I can add paging info to the search string to constrain the results with something like course/1/students?page=1&count=10. Embedding the students collection into the course resource would be a violation of REST. I would not be returning a course, I'd be returning course-and-students.

Tollhouse

Collections are a special consideration in REST based API design because the REST principles places considerable constraints on how they are represented in the results of your queries - Could you elaborate? – Baryton

there are no standards on how these things should be represented and access if you're using anything other than html as a resource type. First, resources are untyped. Second, the media-type negotiated is the standard that defines in which representation format the data is transmitted. IANA is the central registry for media types. If none of the existing types is sufficient you can always define a new one and register it with IANA to increase interop – Gynaecology

Embedding the students collection into the course resource would be a violation of REST - REST actually does not put any emphasis on what resources should contain or what not, other than links and controls of course. REST just defines how server and clients should interact and handle resources in order to avoid coupling to allow servers to evolve freely without having to fear breaking clients. From a HTTP standpoint you just exchange documents so no focus on the content either. However, if caching is in place, which REST enforces, it is questionable whether embedding data yields any benefits – Gynaecology

Answer 2

as I understand it, a REST collection is like a table in sql - we can create new resources inside a table (rows).

instead, a store is like a collection data structure in programming - we can add/remove items, but not create new resources (items). They were already created by some other REST collection.

Malversation