Permalink
Browse files

Merge pull request #2715 from fog/rackspace_storage_docs

Update to attempt to alleviate confusion between Directory.new and get.
  • Loading branch information...
2 parents 573591f + 9e10396 commit dcfabec3de11bed34b5dfaee73fa509d783817ff @elight elight committed Feb 26, 2014
Showing with 27 additions and 0 deletions.
  1. +27 −0 lib/fog/rackspace/docs/storage.md
@@ -269,6 +269,14 @@ To retrieve a specific directory:
service.directories.get "blue"
+**Note** As a general rule, only use `get` when you want to iterate over the contents of a `Directory`
+
+This call is similar to...
+
+ service.directories.new :key => "blue"
+
+... except the `get` method makes an HTTP call that returns metadata for up to the first 10,000 files. **This can be slow!**
+
This returns a `Fog::Storage::Rackspace::Directory` instance:
<Fog::Storage::Rackspace::Directory
@@ -337,6 +345,25 @@ To upload a file into a directory:
**Note**: For files larger than 5 GB please refer to the [Upload Large Files](#upload_large_files) section.
+If you only need a `Directory` so that you can create a file (as above), you can accomplish this without
+an HTTP call as below:
+
+ dir = service.directories.new :key => "blue"
+ file = dir.files.new(...)
+ file.save
+
+This will **not** retrieve the metadata for files in the `Directory`.
+
+However, if the `Directory` does not already exist in Cloud Files, the `save` call will return with a 404.
+
+In this case, you will need to `save` the `Directory` first...
+
+ dir.save
+
+... before you can...
+
+ file.save
+
### Additional Parameters
The `create` method also supports the following key values:

0 comments on commit dcfabec

Please sign in to comment.