From b11bbab320b0d3492839af125601bfa8e05d121e Mon Sep 17 00:00:00 2001
From: Sean Hammond <git@seanh.cc>
Date: Tue, 1 Jul 2014 19:15:53 +0000
Subject: [PATCH] Add examples section to API docs

---
 doc/api/index.rst | 23 ++++++++++++++++++++---
 1 file changed, 20 insertions(+), 3 deletions(-)

diff --git a/doc/api/index.rst b/doc/api/index.rst
index ded191d9749..6231632d893 100644
--- a/doc/api/index.rst
+++ b/doc/api/index.rst
@@ -206,10 +206,8 @@ to import datasets into CKAN.
     created_package = response_dict['result']
     pprint.pprint(created_package)
 
+For more examples, see :ref:`api-examples`.
 
-Here is an example of updating a resource file from the command line.::
-
-    http --json POST http://demo.ckan.org/api/3/action/resource_update id=<resource id> upload=@file.csv url=http://demo.ckan.org/dataset/<dataset name>/resource/<resource id> Authorization:<api key>
 
 
 ------------
@@ -318,6 +316,25 @@ http://demo.ckan.org/api/3/action/package_show?id=adur_district_spending&callbac
 
 .. todo :: This doesn't work with all functions.
 
+
+.. _api-examples:
+
+------------
+API Examples
+------------
+
+
+Uploading a new version of a resource file
+==========================================
+
+You can use the ``upload`` parameter of the
+:py:func:`~ckan.logic.action.update.resource_update` function to upload a
+new version of a resource file. This requires a ``multipart/form-data``
+request, with httpie you can do this using the ``@file.csv``::
+
+    http --json POST http://demo.ckan.org/api/3/action/resource_update id=<resource id> upload=@updated_file.csv Authorization:<api key>
+
+
 .. _api-reference:
 
 --------------------