[#255] Move Util API docs into Legacy API chapter

doc/index.rst

@@ -75,7 +75,6 @@ The CKAN API
 .. toctree::
    :maxdepth: 1
 
-   api-util.rst
    legacy-api
 
 

doc/legacy-api.rst

@@ -408,6 +408,136 @@ The ``Dataset`` and ``Revision`` data formats are as defined in `Model Formats`_
 |                       |               |                                                     | included in the results.         |
 +-----------------------+---------------+-----------------------------------------------------+----------------------------------+
 
+
+The Util API
+~~~~~~~~~~~~
+
+The Util API provides various utility APIs -- e.g. auto-completion APIs used by
+front-end javascript.
+
+All Util APIs are read-only. The response format is JSON. Javascript calls may
+want to use the JSONP formatting.
+
+.. Note::
+
+  Some CKAN deployments have the API deployed at a different domain to the main CKAN website. To make sure that the AJAX calls in the Web UI work, you'll need to configue the ckan.api_url. e.g.::
+
+    ckan.api_url = http://api.example.com/
+
+
+dataset autocomplete
+````````````````````
+
+There an autocomplete API for package names which matches on name or title.
+
+This URL:
+
+::
+
+    /api/2/util/dataset/autocomplete?incomplete=a%20novel
+
+Returns:
+
+::
+
+    {"ResultSet": {"Result": [{"match_field": "title", "match_displayed": "A Novel By Tolstoy (annakarenina)", "name": "annakarenina", "title": "A Novel By Tolstoy"}]}}
+
+
+tag autocomplete
+````````````````
+
+There is also an autocomplete API for tags which looks like this:
+
+This URL:
+
+::
+
+    /api/2/util/tag/autocomplete?incomplete=ru
+
+Returns:
+
+::
+
+    {"ResultSet": {"Result": [{"Name": "russian"}]}}
+
+resource format autocomplete
+````````````````````````````
+
+Similarly, there is an autocomplete API for the resource format field
+which is available at:
+
+::
+
+    /api/2/util/resource/format_autocomplete?incomplete=cs
+
+This returns:
+
+::
+
+    {"ResultSet": {"Result": [{"Format": "csv"}]}}
+
+markdown
+````````
+
+Takes a raw markdown string and returns a corresponding chunk of HTML. CKAN uses the basic Markdown format with some modifications (for security) and useful additions (e.g. auto links to datasets etc. e.g. ``dataset:river-quality``).
+
+Example::
+
+    /api/util/markdown?q=<http://ibm.com/>
+
+Returns::
+
+    "<p><a href="http://ibm.com/" target="_blank" rel="nofollow">http://ibm.com/</a>\n</p>"
+
+is slug valid
+`````````````
+
+Checks a name is valid for a new dataset (package) or group, with respect to it being used already.
+
+Example::
+
+    /api/2/util/is_slug_valid?slug=river-quality&type=package
+
+Response::
+
+    {"valid": true}
+
+munge package name
+``````````````````
+
+For taking an readable identifier and munging it to ensure it is a valid dataset id. Symbols and whitespeace are converted into dashes. Example::
+
+    /api/util/dataset/munge_name?name=police%20spending%20figures%202009
+
+Returns::
+
+    "police-spending-figures-2009"
+
+munge title to package name
+```````````````````````````
+
+For taking a title of a package and munging it to a readable and valid dataset id. Symbols and whitespeace are converted into dashes, with multiple dashes collapsed. Ensures that long titles with a year at the end preserves the year should it need to be shortened. Example::
+
+    /api/util/dataset/munge_title_to_name?title=police:%20spending%20figures%202009
+
+Returns::
+
+    "police-spending-figures-2009"
+
+
+munge tag
+`````````
+
+For taking a readable word/phrase and munging it to a valid tag (name). Symbols and whitespeace are converted into dashes. Example::
+
+    /api/util/tag/munge?tag=water%20quality
+
+Returns::
+
+    "water-quality"
+
+
+
 Status Codes
 ~~~~~~~~~~~~