cloud_files_sdk_brainstorming.rb

# containers
cf.containers.create("new_container")
cf.containers.create("new_container", metadata: { "you're on your own here bud": "because you wanted all of the power" }) # Should we even offer metadata mutation at create time????
container = cf.containers["my-test-dir"]
container.delete

# metadata (Hash-like protocol)
container.metadata                           # Return a Hash of the metadata less the X-Container-Meta- prefixes
container.metadata["price"] = "4.20"
container.metadata.delete("price")
         .readers=(*args)                    # Set list of users with container read privileges
         .readers
         .writers=(*args)                    # Set list of users with container read privileges
         .writers
         .enable_versioning(versions_container = "versions")
         .disable_versioning                 # TODO: Try "X-Remove-Versions-Location" first to see if we support it and then get back to Anne
container.sync_to(remote_container_path, with_key: key)
container.disable_sync                       # Have to remove the sync key per http://openstack.10931.n7.nabble.com/SWIFT-how-to-deactivate-container-sync-for-a-particular-container-td5245.html#a5249

# files
container.all                                # up to 10_000
         .all(limit: 100)                    # with optional limit
         .find_by_name("foo")
         .find_by_name("foo", limit:100)
         .find_by_name_beginning_with("foo") # using the "prefix" feature
         
#file
# TBD

• {page: X, per_page: Y} doesn't work with our API because distributed system where CAP can result in inconsistencies in pagination. It's why OpenStack is using a "limit-marker" approach instead. I'm trying to hide those semantics (because I feel they deviate too much from the Rails/web dev world too much) by hiding the marker and letting the user specify a limit.
• When I said Hash-like, I meant insofar as providing [] and []=(arg) methods and not necessarily making it Enumerable. Granted if being Enumerable is easy, I'd tend to go for it because idiomatic Ruby.
• RE: batching operations, the question is where to draw the line. There are a lot of orthogonal pieces of metadata that are all updatable via the same API call. But they're orthogonal. Grouping them together in a single API call could make the SDK less clear.
• I had initially considered the "list methods" approach, as you described it but I could see it leading to an explosion of methods on the CloudFiles class. I was hesitant to introduce the Containers class. I'm still considering axing it and pulling its behavior back into the CloudFiles class. My concern is that I can see CloudFiles becoming too cluttered already. I prematurely (my emphasis) extracted Containers as just a logical grouping for behaviors related to containers; it doesn't have any state of its own. So there's another SDK option:

file = cf["container-name"]["file-name"]

... but that starts to feel more like PERL or really bad Ruby as it its unclear to the reader what the first and second calls to [] are doing.