[#255] Edit FileStore API docs

Move the FileStore API docs into its own file (filestore-api.rst) same as the Action API and DataStore API, and move it to the CKAN API section in the table of contents. Also renamed it Storage API -> FileStore API (since the feature is called the FileStore), and added a link to the ckanclient code that shows how to use it (since the documentation is hopeless). On the FileStore page, where the FileStore API docs used to be put a link to the new FileStore API page. Edited the FileStore feature docs: rename Storage Web Interface -> FileStore Web Interface (the feature seems to change names, from FileStore to just Storage, half-way down the page).
ckan · Feb 8, 2013 · ea68b96 · ea68b96
1 parent a6c5236
commit ea68b96
Show file tree

Hide file tree

Showing 3 changed files with 94 additions and 82 deletions.
diff --git a/doc/filestore-api.rst b/doc/filestore-api.rst
@@ -0,0 +1,87 @@
+The FileStore API
+=================
+
+CKAN's FileStore API lets you upload files to CKAN's
+:doc:`FileStore <filestore>`. If you're looking for an example,
+`ckanclient <https://github.com/okfn/ckanclient>`_ contains
+`Python code for uploading a file to CKAN using the FileStore API <https://github.com/okfn/ckanclient/blob/master/ckanclient/__init__.py#L546>`_.
+
+
+FileStore Metadata API
+----------------------
+
+The API is located at::
+
+     /api/storage/metadata/{label}
+
+It supports the following methods:
+
+* GET will return the metadata
+* POST will add/update metadata
+* PUT will replace metadata
+
+Metadata is a json dict of key values which for POST and PUT should be send in body of request.
+
+A standard response looks like::
+
+    {
+      "_bucket": "ckannet-storage",
+      _content_length: 1074
+      _format: "text/plain"
+      _label: "/file/8630a664-0ae4-485f-99c2-126dae95653a"
+      _last_modified: "Fri, 29 Apr 2011 19:27:31 GMT"
+      _location: "some-location"
+      _owner: null
+      uploaded-by: "bff737ef-b84c-4519-914c-b4285144d8e6"
+    }
+
+Note that values with '_' are standard OFS metadata and are mostly read-only -- _format i.e. content-type can be set).
+
+
+FileStore Form Authentication API
+---------------------------------
+
+Provides credentials for doing operations on storage directly from a client
+(using web form style POSTs).
+
+The API is located at::
+
+    /api/storage/auth/form/{label}
+
+Provide fields for a form upload to storage including authentication::
+
+    :param label: label.
+    :return: json-encoded dictionary with action parameter and fields list.
+
+
+FileStore Request Authentication API
+------------------------------------
+
+Provides credentials for doing operations on storage directly from a client.
+
+.. warning:: This API is currently disabled and will likely be deprecated.
+             Use the form authentication instead.
+
+The API is at::
+
+    /api/storage/auth/request/{label}
+
+Provide authentication information for a request so a client can
+interact with backend storage directly::
+
+    :param label: label.
+    :param kwargs: sent either via query string for GET or json-encoded
+        dict for POST). Interpreted as http headers for request plus an
+        (optional) method parameter (being the HTTP method).
+
+        Examples of headers are:
+
+            Content-Type
+            Content-Encoding (optional)
+            Content-Length
+            Content-MD5
+            Expect (should be '100-Continue')
+
+    :return: is a json hash containing various attributes including a
+    headers dictionary containing an Authorization field which is good for
+    15m.
diff --git a/doc/filestore.rst b/doc/filestore.rst
@@ -61,94 +61,18 @@ For S3::
    ofs.aws_secret_access_key = ....
 
 
-Storage Web Interface
-=====================
+FileStore Web Interface
+=======================
 
 Upload of files to storage is integrated directly into the the Dataset creation
 and editing system with files being associated to Resources.
 
 
-Storage API
-===========
-
-Metadata API
-------------
-
-The API is located at::
-
-     /api/storage/metadata/{label}
-
-It supports the following methods:
-
-  * GET will return the metadata
-  * POST will add/update metadata
-  * PUT will replace metadata
-
-Metadata is a json dict of key values which for POST and PUT should be send in body of request.
-
-A standard response looks like::
-
-    {
-      "_bucket": "ckannet-storage",
-      _content_length: 1074
-      _format: "text/plain"
-      _label: "/file/8630a664-0ae4-485f-99c2-126dae95653a"
-      _last_modified: "Fri, 29 Apr 2011 19:27:31 GMT"
-      _location: "some-location"
-      _owner: null
-      uploaded-by: "bff737ef-b84c-4519-914c-b4285144d8e6"
-    }
-
-Note that values with '_' are standard OFS metadata and are mostly read-only -- _format i.e. content-type can be set).
-
-
-Form Authentication
--------------------
-
-Provides credentials for doing operations on storage directly from a client
-(using web form style POSTs).
-
-The API is located at::
-
-    /api/storage/auth/form/{label}
-
-Provide fields for a form upload to storage including authentication::
-
-    :param label: label.
-    :return: json-encoded dictionary with action parameter and fields list.
-
-
-Request Authentication API
---------------------------
-
-Provides credentials for doing operations on storage directly from a client.
-
-.. warning:: this API is currently disabled and will likely be deprecated. Use the
-             form authentication instead.
-
-The API is at::
-
-    /api/storage/auth/request/{label}
-
-Provide authentication information for a request so a client can
-interact with backend storage directly::
-
-    :param label: label.
-    :param kwargs: sent either via query string for GET or json-encoded
-        dict for POST). Interpreted as http headers for request plus an
-        (optional) method parameter (being the HTTP method).
-
-        Examples of headers are:
-
-            Content-Type
-            Content-Encoding (optional)
-            Content-Length
-            Content-MD5
-            Expect (should be '100-Continue')
+FileStore API
+=============
 
-    :return: is a json hash containing various attributes including a
-    headers dictionary containing an Authorization field which is good for
-    15m.
+The :doc:`FileStore API <filestore-api>` is CKAN's API for uploading files to
+the FileStore.
 
 
 DataStore Integration

diff --git a/doc/index.rst b/doc/index.rst
@@ -71,6 +71,7 @@ The CKAN API
 
    api
    datastore-api
+   filestore-api
 
 .. toctree::
    :maxdepth: 1