From ea68b96a974f138b77c924d8880b54a0a91c0cb1 Mon Sep 17 00:00:00 2001 From: Sean Hammond Date: Fri, 8 Feb 2013 10:27:06 +0100 Subject: [PATCH] [#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). --- doc/filestore-api.rst | 87 ++++++++++++++++++++++++++++++++++++++++++ doc/filestore.rst | 88 +++---------------------------------------- doc/index.rst | 1 + 3 files changed, 94 insertions(+), 82 deletions(-) create mode 100644 doc/filestore-api.rst diff --git a/doc/filestore-api.rst b/doc/filestore-api.rst new file mode 100644 index 00000000000..c61a83085bf --- /dev/null +++ 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 `. If you're looking for an example, +`ckanclient `_ contains +`Python code for uploading a file to CKAN using the FileStore API `_. + + +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 index a670fba98a4..f2c75a1ff6d 100644 --- 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 ` is CKAN's API for uploading files to +the FileStore. DataStore Integration diff --git a/doc/index.rst b/doc/index.rst index 6693c341e73..7d1913d3807 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -71,6 +71,7 @@ The CKAN API api datastore-api + filestore-api .. toctree:: :maxdepth: 1