How to model a storage repository which provides intelligent REST based access

I am looking for a unique way to query the following use cases in a REST fashion:-

Assuming the repository contains the following:-

a. green color ball image of 1cm radius
b. yellow color ball image of 1cm radius
c. blue color ball image of 1cm radius
d. green color ball image of 2cm radius
e. yellow color ball image of 2cm radius
f. blue color ball image of 2cm radius
g. computer monitor icon image of size 32x32 pixels in png format
h. computer monitor icon image of size 64x64 pixels in png format
i. computer monitor icon image of size 32x32 pixels in ico format
j. computer monitor icon image of size 64x64 pixels in ico format
k. HR travel policy
l. HR new hire policy
g. HR promotion policy

1. Find all documents published after a certain date?
2. Find all documents published before a certain date?
3. Find all documents published between a certain set of dates?
4. Find all balls which are 1cm in radius
5. Find all documents whose download format is "png"
6. Find all documents whose size is 32x32 pixels
7. Find all balls which are green in color.

Our storage repository could be based on Google Storage, Amazon S3, Mongodb GridFS, Java content repository (JCR 2.0) or a simple file system.

What would be the ideal way to store and retrieve the above data. I would like the REST URL to be as expressive as possible, so that I can model any of the above use cases [1-6]. Appreciate any pointers on how to design a generic repository, so that I can use appropriate naming conventions to fetch documents ba开发者_运维问答sed on the above queries.

---

I would recommend separating two concerns here: 1) modelling storage repository; and 2) designing RESTful access. When a development just starts, these two concerns always go hand in hand. As a project evolves, you might need to design aggregate points or simply different points of view for the repository. It's always good to understand that the concepts are similar only on a surface.

As far as your 7 questions go, first you need to decide if a concept of a "document" is fully replaceable by a concept of "document instance". For example, if a red ball has ID of 1 then are the following two resources valid?

/documents/1
/balls/1

Can you POST a new ball to the both of the following resources or just one?

/documents/
/balls/

Can you find all green balls by a single or multiple resources?

/documents/type/ball/by/color/green
/balls/by/color/green

It's important to answer those questions so that your API is unambiguous.

Second, you need to decide how "SEO-friendly" you want your resource to look. For example:

1. /documents/after-date/2001-01-01/
2. /documents/before-date/2010-12-31/
3. /documents/after-date/2001-01-01/before-date/2010-12-31/
7. /balls/by/color/green

or

1. /documents?after-date=2001-01-01
2. /documents?before-date=2010-12-31
3. /documents?after-date=2001-01-01&before-date=2010-12-31
7. /balls?color=green

This is a "concern" if your API is wide open and is used to drive links on a public web site. The reason why I put "SEO-friendly" and "concern" in quotes is because SEO experts still don't agree if search engines prefer one way or another or the engines don't care at all.

From the implementation point of view, it's easier, faster and more scalable to use URL parameters. But if you don't expect crazy amount of combinations then both approaches will work equally well.

From a personal experience I would also recommend to group search-type resources (as oppose to identity resources) with a common path. For example:

7. /balls/search?color=green

instead of 

7. /balls?color=green

Good luck with a design. There is no one right way when it comes to REST. As long as it makes sense - you're on a good path.