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

Answer 1

Imagine you are in a library. You go through the shelves to find the book you want. When you find the book you want, you can add it to your own bookshelf in the library.

Here all the shelves are the collection. Your own bookshelf is the storage.

If you want to donate books to the library, you POST to the library. Because a book has indeed been added. However, when you add one of the books from all the shelves to your own bookshelf, you make a PUT. Because the number of books in the library has not changed.

A collection resource is a server-managed directory of resources.A store is a client-managed resource repository.

You want to donate a book to the library, but the library director doesn't like your book and rejects it. You are the client and the director is the server.

Collection (Server-Managed)

Clients can propose new resources, but the server controls the location.

# Creating a new user - Collection example
POST /users
{
    "name": "John",
    "email": "john@example.com"
}

# Server decides the location
Response: 201 Created
Location: /users/789

Store (Client-Managed)

Client decides exactly where to put the resource.

# Adding a user to a group - Store example
PUT /groups/132/members/789
{
    "joinDate": "2024-12-16"
}

# Client specifies the exact location
Response: 201 Created

More Examples

Collection Examples

# Creating a post
POST /posts
{
    "title": "My First Post",
    "content": "Hello World"
}
# Server assigns: /posts/456

# Creating a book
POST /books
{
    "title": "Lord of the Rings",
    "author": "Tolkien"
}
# Server assigns: /books/123

Store Examples

# Bookmarking a post
PUT /users/789/bookmarks/post-456
{
    "savedDate": "2024-12-16"
}

# Setting user preferences
PUT /users/789/preferences/theme
{
    "mode": "dark",
    "color": "blue"
}

Common Usage Patterns

POST /users                          # Collection (server assigns user ID)
PUT /groups/123/members/789          # Store (client specifies location)
POST /products                       # Collection (server manages product IDs)
PUT /users/789/cart/product-456      # Store (client manages cart items)

Key Difference

• Collection: "Here's a resource, you (server) decide where to put it"
• Store: "Put this resource exactly here (client specifies location)"enter

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.

Answer 3

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.