[ckan-changes] commit/ckan: 2 new changesets
Bitbucket
commits-noreply at bitbucket.org
Fri Jul 29 11:03:17 UTC 2011
2 new changesets in ckan:
http://bitbucket.org/okfn/ckan/changeset/375463fa8f6b/
changeset: 375463fa8f6b
branch: release-v1.4.3
user: dread
date: 2011-07-29 13:02:33
summary: [doc]: Put all API docs in one file. References wiki pages with all the examples.
affected #: 49 files (28.0 KB)
--- a/doc/api.rst Fri Jul 29 10:48:47 2011 +0100
+++ b/doc/api.rst Fri Jul 29 12:02:33 2011 +0100
@@ -1,41 +1,537 @@
-.. |site| replace:: CKAN
-
-.. |api| replace:: API
-
-.. |base_location| replace:: ``http://ckan.net/api``
-
-.. |usage| replace:: to view and change
-
-.. |version_1_location| replace:: ``http://ckan.net/api/1``
-
-.. |version_2_location| replace:: ``http://ckan.net/api/2``
-
-.. |version_1_doc| replace:: :doc:`api/version1`
-
-.. |version_2_doc| replace:: :doc:`api/version2`
-
-.. #|version_3_doc| replace:: :doc:`api/version3`
-
.. index:: API
===========================
-Reference: The |site| |api|
+Reference: CKAN API
===========================
.. toctree::
:hidden:
:maxdepth: 1
-The |site| |api| presents the catalog of metadata behind |site|.
+The CKAN API provides programmatic access to the catalog of metadata stored in CKAN.
-.. note:: This section contains general information about the |site| API. If you are looking for API documentation, please see |version_2_doc|.
+Overview
+--------
-.. include:: api/overview.rst.inc
+The CKAN data catalog is not only available in a web browser, but also
+via its Application Programming Interface (API).
-.. include:: api/versions.rst.inc
+The API can be used to view and change the catalog. This document describes the
+resource locations, data formats, and status codes which comprise the CKAN
+API, so that anyone can create software applications that use the API
+service.
-.. include:: api/clients.rst.inc
+The CKAN API follows the RESTful (Representational State
+Transfer) style. Resource locations are separated both from the methods
+supported by the resources, and from the data formats and status codes
+used by the methods.
-.. include:: api/example.rst.inc
+Examples
+--------
+For a tutorial and examples of using the CKAN API, see: http://wiki.ckan.net/Using_the_API
+Code Modules for Client Applications
+-------------------------------------
+
+There are also some code modules (Python, PHP, Drupal, Perl etc.) that provide
+convenient wrappers around much of the CKAN API. For full details of these,
+please consult http://wiki.ckan.net/API
+
+Versions
+--------
+
+The CKAN API is versioned, so that backwards incompatible changes can be
+introduced without removing existing support. A particular version of the API
+can be used by including its version number after the API location and before
+the resource location.
+
+If the API version is not specified in the request, then the API will default to version 1.
+
+Versions 1 & 2
+~~~~~~~~~~~~~~
+
+These are very similar, but when the API returns a reference to an object, Version 1 API will return the Name of the object (e.g. "river-pollution") and Version 2 API will return the ID of the object (e.g. "a3dd8f64-9078-4f04-845c-e3f047125028").
+
+The reason for this is that Names can change, so to reliably refer to the same package every time, you will want to use the ID and therefore use API v2. Alternatively, many people prefer to deal with Names, so API v1 suits them.
+
+When making requests, you can call objects by either their Name or ID, interchangeably.
+
+The only exception for this is for Tag objects. Since Tag names are immutable, they are always referred to with their Name.
+
+
+API Details - Versions 1 & 2
+----------------------------
+
+Overview
+~~~~~~~~
+
+The CKAN data catalog is not only available in a web browser, but also
+via its Application Programming Interface (API).
+
+The API can be used to view and change the catalog. This document describes the
+resource locations, data formats, and status codes which comprise the CKAN
+API, so that anyone can create software applications that use the API
+service.
+
+The CKAN API follows the RESTful (Representational State
+Transfer) style. Resource locations are separated both from the methods
+supported by the resources, and from the data formats and status codes
+used by the methods.
+
+
+The CKAN API version 1 & 2 is separated into three parts.
+
+* `Model API`_
+* `Search API`_
+* `Util API`_
+
+The resources, methods, and data formats of each are described below.
+
+Locators
+~~~~~~~~
+
+The locator for a given resource can be formed by appending
+the relative path for that resource to the API locator.
+
+ ``Resource Locator = API Locator + Resource Path``
+
+The API locators for the CKAN APIs (by version) are:
+
+ * ``http://ckan.net/api`` (version 1)
+ * ``http://ckan.net/api/1`` (version 1)
+ * ``http://ckan.net/api/2`` (version 2)
+
+The relative paths for each resource are listed in the sections below.
+
+Model API
+~~~~~~~~~
+
+Model resources are available at published locations. They are represented with
+a variety of data formats. Each resource location supports a number of methods.
+
+The data formats of the requests and the responses are defined below.
+
+Model Resources
+```````````````
+
+Here are the resources of the Model API.
+
+
++--------------------------------+-------------------------------------------------------------------+
+| Model Resource | Location |
++================================+===================================================================+
+| Package Register | ``/rest/package`` |
++--------------------------------+-------------------------------------------------------------------+
+| Package Entity | ``/rest/package/PACKAGE-REF`` |
++--------------------------------+-------------------------------------------------------------------+
+| Group Register | ``/rest/group`` |
++--------------------------------+-------------------------------------------------------------------+
+| Group Entity | ``/rest/group/GROUP-REF`` |
++--------------------------------+-------------------------------------------------------------------+
+| Tag Register | ``/rest/tag`` |
++--------------------------------+-------------------------------------------------------------------+
+| Tag Entity | ``/rest/tag/TAG-NAME`` |
++--------------------------------+-------------------------------------------------------------------+
+| Rating Register | ``/rest/rating`` |
++--------------------------------+-------------------------------------------------------------------+
+| Package Relationships Register | ``/rest/package/PACKAGE-REF/relationships`` |
++--------------------------------+-------------------------------------------------------------------+
+| Package Relationships Register | ``/rest/package/PACKAGE-REF/RELATIONSHIP-TYPE`` |
++--------------------------------+-------------------------------------------------------------------+
+| Package Relationships Register | ``/rest/package/PACKAGE-REF/relationships/PACKAGE-REF`` |
++--------------------------------+-------------------------------------------------------------------+
+| Package Relationship Entity | ``/rest/package/PACKAGE-REF/RELATIONSHIP-TYPE/PACKAGE-REF`` |
++--------------------------------+-------------------------------------------------------------------+
+| Package\'s Revisions Entity | ``/rest/package/PACKAGE-REF/revisions`` |
++--------------------------------+-------------------------------------------------------------------+
+| Revision Register | ``/rest/revision`` |
++--------------------------------+-------------------------------------------------------------------+
+| Revision Entity | ``/rest/revision/REVISION-ID`` |
++--------------------------------+-------------------------------------------------------------------+
+| License List | ``/rest/licenses`` |
++--------------------------------+-------------------------------------------------------------------+
+
+Possible values for PACKAGE-REF are the package id, or the current package name.
+
+Possible values for RELATIONSHIP-TYPE are described in the Relationship-Type data format.
+
+
+Model Methods
+`````````````
+
+Here are the methods of the Model API.
+
++-------------------------------+--------+------------------+-------------------+
+| Resource | Method | Request | Response |
++===============================+========+==================+===================+
+| Package Register | GET | | Package-List |
++-------------------------------+--------+------------------+-------------------+
+| Package Register | POST | Package | |
++-------------------------------+--------+------------------+-------------------+
+| Package Entity | GET | | Package |
++-------------------------------+--------+------------------+-------------------+
+| Package Entity | PUT | Package | |
++-------------------------------+--------+------------------+-------------------+
+| Group Register | GET | | Group-List |
++-------------------------------+--------+------------------+-------------------+
+| Group Register | POST | Group | |
++-------------------------------+--------+------------------+-------------------+
+| Group Entity | GET | | Group |
++-------------------------------+--------+------------------+-------------------+
+| Group Entity | PUT | Group | |
++-------------------------------+--------+------------------+-------------------+
+| Tag Register | GET | | Tag-List |
++-------------------------------+--------+------------------+-------------------+
+| Tag Entity | GET | | Package-List |
++-------------------------------+--------+------------------+-------------------+
+| Rating Register | POST | Rating | |
++-------------------------------+--------+------------------+-------------------+
+| Rating Entity | GET | | Rating |
++-------------------------------+--------+------------------+-------------------+
+| Package Relationships Register| GET | | Pkg-Relationships |
++-------------------------------+--------+------------------+-------------------+
+| Package Relationship Entity | GET | | Pkg-Relationship |
++-------------------------------+--------+------------------+-------------------+
+| Package Relationship Entity | PUT | Pkg-Relationship | |
++-------------------------------+--------+------------------+-------------------+
+| Package\'s Revisions Entity | GET | | Pkg-Revisions |
++-------------------------------+--------+------------------+-------------------+
+| Revision List | GET | | Revision-List |
++-------------------------------+--------+------------------+-------------------+
+| Revision Entity | GET | | Revision |
++-------------------------------+--------+------------------+-------------------+
+| License List | GET | | License-List |
++-------------------------------+--------+------------------+-------------------+
+
+* POSTing data to a register resource will create a new entity.
+
+* PUT/POSTing data to an entity resource will update an existing entity.
+
+* PUT operations may instead use the HTTP POST method.
+
+Model Formats
+`````````````
+
+Here are the data formats for the Model API.
+
+.. |format-package-ref| replace:: Package-Ref
+
+.. |format-package-register| replace:: [ |format-package-ref|, |format-package-ref|, |format-package-ref|, ... ]
+
+.. |format-package-entity| replace:: { id: Uuid, name: Name-String, title: String, version: String, url: String, resources: [ Resource, Resource, ...], author: String, author_email: String, maintainer: String, maintainer_email: String, license_id: String, tags: Tag-List, notes: String, extras: { Name-String: String, ... } }
+
+.. |format-group-ref| replace:: Group-Ref
+
+.. |format-group-register| replace:: [ |format-group-ref|, |format-group-ref|, |format-group-ref|, ... ]
+
+.. |format-group-entity| replace:: { name: Name-String, title: String, description: String, packages: Package-List }
+
+
+To send request data, create the JSON-format string (encode in UTF8) put it in the request body and send it using PUT or POST.
+
+Response data will be in the response body in JSON format.
+
+Notes:
+
+ * When you update an object, fields that you don't supply will remain as they were before.
+
+ * To delete an 'extra' key-value pair, supply the key with JSON value: ``null``
+
+ * When you read a package then some additional information is supplied that cannot current be adjusted throught the CKAN API. This includes info on Package Relationship ('relationships'), Group membership ('groups'), ratings ('ratings_average' and 'ratings_count'), full URL of the package in CKAN ('ckan_url') and Package ID ('id'). This is purely a convenience for clients, and only forms part of the Package on GET.
+
+Search API
+~~~~~~~~~~
+
+Search resources are available at published locations. They are represented with
+a variety of data formats. Each resource location supports a number of methods.
+
+The data formats of the requests and the responses are defined below.
+
+Search Resources
+````````````````
+
+Here are the published resources of the Search API.
+
++---------------------------+--------------------------+
+| Search Resource | Location |
++===========================+==========================+
+| Package Search | ``/search/package`` |
++---------------------------+--------------------------+
+| Resource Search | ``/search/resource`` |
++---------------------------+--------------------------+
+| Revision Search | ``/search/revision`` |
++---------------------------+--------------------------+
+| Tag Counts | ``/tag_counts`` |
++---------------------------+--------------------------+
+
+See below for more information about package and revision search parameters.
+
+Search Methods
+``````````````
+
+Here are the methods of the Search API.
+
++-------------------------------+--------+------------------------+--------------------------+
+| Resource | Method | Request | Response |
++===============================+========+========================+==========================+
+| Package Search | POST | Package-Search-Params | Package-Search-Response |
++-------------------------------+--------+------------------------+--------------------------+
+| Resource Search | POST | Resource-Search-Params | Resource-Search-Response |
++-------------------------------+--------+------------------------+--------------------------+
+| Revision Search | POST | Revision-Search-Params | Revision-List |
++-------------------------------+--------+------------------------+--------------------------+
+| Tag Counts | GET | | Tag-Count-List |
++-------------------------------+--------+------------------------+--------------------------+
+
+It is also possible to supply the search parameters in the URL of a GET request,
+for example ``/api/search/package?q=geodata&allfields=1``.
+
+Search Formats
+``````````````
+
+Here are the data formats for the Search API.
+
++-------------------------+------------------------------------------------------------+
+| Name | Format |
++=========================+============================================================+
+| Package-Search-Params | { Param-Key: Param-Value, Param-Key: Param-Value, ... } |
+| Resource-Search-Params | See below for full details of search parameters across the |
+| Revision-Search-Params | various domain objects. |
++-------------------------+------------------------------------------------------------+
+| Package-Search-Response | { count: Count-int, results: [Package, Package, ... ] } |
++-------------------------+------------------------------------------------------------+
+| Resource-Search-Response| { count: Count-int, results: [Resource, Resource, ... ] } |
++-------------------------+------------------------------------------------------------+
+| Revision-List | [ Revision-Id, Revision-Id, Revision-Id, ... ] |
+| | NB: Ordered with youngest revision first |
++-------------------------+------------------------------------------------------------+
+| Tag-Count-List | [ [Name-String, Integer], [Name-String, Integer], ... ] |
++-------------------------+------------------------------------------------------------+
+
+The ``Package`` and ``Revision`` data formats are as defined in `Model Formats`_.
+
+**Package Parameters**
+
++-----------------------+---------------+----------------------------------+----------------------------------+
+| Param-Key | Param-Value | Examples | Notes |
++=======================+===============+==================================+==================================+
+| q | Search-String || q=geodata | Criteria to search the package |
+| | || q=government+sweden | fields for. URL-encoded search |
+| | || q=%22drug%20abuse%22 | text. (You can also concatenate |
+| | | | words with a '+' symbol in a |
+| | | | URL.) Search results must contain|
+| | | | all the specified words. |
++-----------------------+---------------+----------------------------------+----------------------------------+
+| qjson | JSON encoded | ['q':'geodata'] | All search parameters can be |
+| | options | | json-encoded and supplied to this|
+| | | | parameter as a more flexible |
+| | | | alternative in GET requests. |
++-----------------------+---------------+----------------------------------+----------------------------------+
+|title, | Search-String || title=uk&tags=health+census | Search in a particular a field. |
+|tags, notes, groups, | || department=environment | |
+|author, maintainer, | | | |
+|update_frequency, or | | | |
+|any 'extra' field name | | | |
+|e.g. department | | | |
++-----------------------+---------------+----------------------------------+----------------------------------+
+| order_by | field-name | order_by=name | Specify either rank or the field |
+| | (default=rank)| | to sort the results by |
++-----------------------+---------------+----------------------------------+----------------------------------+
+| offset, limit | result-int | offset=40&limit=20 | Pagination options. Offset is the|
+| | (defaults: | | number of the first result and |
+| | offset=0, | | limit is the number of results to|
+| | limit=20) | | return. |
++-----------------------+---------------+----------------------------------+----------------------------------+
+| all_fields | 0 (default) | all_fields=1 | Each matching search result is |
+| | or 1 | | given as either a package name |
+| | | | (0) or the full package record |
+| | | | (1). |
++-----------------------+---------------+----------------------------------+----------------------------------+
+| filter_by_openness | 0 (default) | filter_by_openness=1 | Filters results by ones which are|
+| | or 1 | | open. |
++-----------------------+---------------+----------------------------------+----------------------------------+
+|filter_by_downloadbable| 0 (default) | filter_by_downloadable=1 | Filters results by ones which |
+| | or 1 | | have at least one resource URL. |
++-----------------------+---------------+----------------------------------+----------------------------------+
+
+**Resource Parameters**
+
++-----------------------+---------------+-----------------------------------------+----------------------------------+
+| Param-Key | Param-Value | Example | Notes |
++=======================+===============+=========================================+==================================+
+| url, format, | Search-String || url=statistics.org | Criteria to search the package |
+| description | || format=xls | fields for. URL-encoded search |
+| | || description=Research+Institute | text. This search string must be |
+| | | | found somewhere within the field |
+| | | | to match. |
+| | | | Case insensitive. |
++-----------------------+---------------+-----------------------------------------+----------------------------------+
+| qjson | JSON encoded | ['url':'www.statistics.org'] | All search parameters can be |
+| | options | | json-encoded and supplied to this|
+| | | | parameter as a more flexible |
+| | | | alternative in GET requests. |
++-----------------------+---------------+-----------------------------------------+----------------------------------+
+| hash | Search-String |hash=b0d7c260-35d4-42ab-9e3d-c1f4db9bc2f0| Searches for an match of the |
+| | | | hash field. An exact match or |
+| | | | match up to the length of the |
+| | | | hash given. |
++-----------------------+---------------+-----------------------------------------+----------------------------------+
+| all_fields | 0 (default) | all_fields=1 | Each matching search result is |
+| | or 1 | | given as either an ID (0) or the |
+| | | | full resource record |
++-----------------------+---------------+-----------------------------------------+----------------------------------+
+| offset, limit | result-int | offset=40&limit=20 | Pagination options. Offset is the|
+| | (defaults: | | number of the first result and |
+| | offset=0, | | limit is the number of results to|
+| | limit=20) | | return. |
++-----------------------+---------------+-----------------------------------------+----------------------------------+
+
+**Revision Parameters**
+
++-----------------------+---------------+-----------------------------------------------------+----------------------------------+
+| Param-Key | Param-Value | Example | Notes |
++=======================+===============+=====================================================+==================================+
+| since_time | Date-Time | since_time=2010-05-05T19:42:45.854533 | The time can be less precisely |
+| | | | stated (e.g 2010-05-05). |
++-----------------------+---------------+-----------------------------------------------------+----------------------------------+
+| since_id | Uuid | since_id=6c9f32ef-1f93-4b2f-891b-fd01924ebe08 | The stated id will not be |
+| | | | included in the results. |
++-----------------------+---------------+-----------------------------------------------------+----------------------------------+
+
+API Keys
+~~~~~~~~
+
+You will need to supply an API Key for certain requests to the CKAN API:
+
+* For any action which makes a change to a resource (i.e. all POST methods on register resources, and PUT/POST methods on entity resources).
+
+* If the particular resource's authorization set-up is not open to
+ visitors for the action.
+
+To obtain your API key:
+
+1. Log-in to the particular CKAN website: /user/login
+
+2. The user page has a link to the API Key: /user/apikey
+
+The key should be passed in the API request header:
+
+================= =====
+Header Example value
+================= =====
+Authorization ``fde34a3c-b716-4c39-8dc4-881ba115c6d4``
+================= =====
+
+If requests that are required to be authorized are not sent with a
+valid Authorization header, for example the user associated with the
+key is not authorized for the operation, or the header is somehow malformed,
+then the requested operation will not be carried out and the CKAN API will
+respond with status code 403.
+
+For more information about HTTP Authorization header, please refer to section
+14.8 of `RFC 2616 <http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.8>`_.
+
+
+Status Codes
+~~~~~~~~~~~~
+
+Standard HTTP status codes are used to signal method outcomes.
+
+===== =====
+Code Name
+===== =====
+200 OK
+201 OK and new object created (referred to in the Location header)
+301 Moved Permanently
+400 Bad Request
+403 Not Authorized
+404 Not Found
+409 Conflict (e.g. name already exists)
+500 Service Error
+===== =====
+
+JSONP formatted responses
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To cater for scripts from other sites that wish to access the API, the data can be returned in JSONP format, where the JSON data is 'padded' with a function call. The function is named in the 'callback' parameter.
+
+Example normal request::
+
+ GET /api/rest/package/pollution_stats
+ returns: {"name": "pollution_stats", ... }
+
+but now with the callback parameter::
+
+ GET /api/rest/package/pollution_stats?callback=jsoncallback
+ returns: jsoncallback({"name": "pollution_stats", ... });
+
+This parameter can apply to all GET requests in the API.
+
+
+Util API
+~~~~~~~~
+
+Some of CKAN's client-side Javascript code makes calls to the CKAN API. For
+example, to generate a suggestion for a package name when adding a new package
+the following API call is made:
+
+::
+
+ /api/2/util/package/create_slug?title=Package+1+Title+Typed+So+Far
+
+The return value is a JSON data structure:
+
+::
+
+ {"valid": true, "name": "package_1_title_typed_so_far"}
+
+These are the keys returned:
+
+``valid``
+
+ Can be ``True`` or ``False``. It is ``true`` when the title entered can be
+ successfully turned into a package name and when that package name is not
+ already being used. It is ``false`` otherwise.
+
+``name``
+
+ The suggested name for the package, based on the title
+
+You can also add ``callback=callback`` to have the response returned as JSONP. eg:
+
+This URL:
+
+::
+
+ /api/2/util/package/create_slug?title=Package+1+Title+Typed+So+Far&callback=callback
+
+Returns:
+
+::
+
+ callback({"valid": true, "name": "package_1_title_typed_so_far"});
+
+In some CKAN deployments you may have the API deployed at a different domain
+from the main CKAN code. In these circumstances you'll need to add a new option
+to the config file to tell the new package form where it should make its API
+requests to:
+
+::
+
+ ckan.api_url = http://api.example.com/
+
+
+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"}]}}
--- a/doc/api/3/example.rst.inc Fri Jul 29 10:48:47 2011 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,43 +0,0 @@
-Example of Usage
-----------------
-
-Let's say you're using ckan.net and want a list of all the packages. If you GET
-`<http://ckan.net/api/rest/package>`_ then it will return the list of the package
-names in JSON format::
-
-["2000-us-census-rdf", "32000-naples-florida-businesses-kml", "aaoe-87", "acawiki", "adb-sdbs", "addgene", "advances-in-dental-research", ... ]
-
-There are several ways you might access this URL:
-
-* simply put this URL into your web browser and save the resulting text file
-
-* you could use a command-line program such as `curl` or `wget`
-
-* you could write a program that uses an http library
-
-* use the Python library `CKAN Client <http://pypi.python.org/pypi/ckanclient>`_
-
-* use command-line tool `Datapkg <http://packages.python.org/datapkg/>`_. It manages datasets in a similar way as getting software packages with `apt-get` or `CPAN`.
-
-You could search for packages to do with 'open street map' like this: `<http://ckan.net/api/search/package?q=open+street+map>`_ returning::
-
-{"count": 4, "results": ["uk-naptan-osm", "osm-uk", "osm", "naptan"]}
-
-You can see the full record for the `osm` package in JSON format with this: `<http://ckan.net/api/rest/package/osm>`_ which returns::
-
-{"id": "a3dd8f64-9078-4f04-845c-e3f047125028", "name": "osm", "title": "Open Street Map", "version": null, "url": "http://www.openstreetmap.org/", ... }
-
-You might add a tag by a PUT to ``http://ckan.net/api/rest/package/osm`` with this data::
-
-{"tags": ["navigation", "openstreetmap", "map", "geo", "geodata", "xml", "publicdomain", "osm", "my-new-tag"]}
-
-Here we use `curl` to create a new package::
-
-$ curl http://test.ckan.net/api/rest/package -d '{"name":"test", "title":"Test package"}' -H "Authorization: 474d34e4-b710-4b77-b89f-2e909c336b91"
-
-And we create an example package with some government data::
-
-$ curl http://test.ckan.net/api/rest/package -d '{"name": "abstract_of_scottish_agricultural_statistics", "title": "Abstract of Scottish Agricultural Statistics", "version": null, "url": null, "author": "Scottish Government", "author_email": null, "maintainer": null, "maintainer_email": null, "notes": "A long term series of all the main agriculture census items collected in the June census.\n\nSource agency: Scottish Government\n\nDesignation: National Statistics\n\nLanguage: English\n\nAlternative title: Abstract of Scottish Agricultural Statistics", "license_id": "ukcrown-withrights", "tags": ["farm-outputs", "environment", "agriculture", "farming", "agriculture-and-environment"], "extras": {"geographic_coverage": "010000: Scotland", "geographical_granularity": "Country", "external_reference": "ONSHUB", "temporal_granularity": "", "date_updated": "", "agency": "", "precision": "", "temporal_coverage_to": "", "temporal_coverage_from": "", "national_statistic": "yes", "import_source": "ONS-ons_data_50_days_to_2010-05-04", "department": "Scottish Government", "update_frequency": "", "date_released": "2010-03-17", "categories": "Agriculture and Environment"}, "resources": [{"url": "http://www.scotland.gov.uk/Topics/Statistics/Browse/Agriculture-Fisheries", "description": "1982-2008 | hub/id/119-33192", "format": ""}, {"url": "http://www.scotland.gov.uk/Topics/Statistics/Browse/Agriculture-Fisheries", "description": "1982-2007 | hub/id/119-34917", "format": ""}, {"url": "http://www.scotland.gov.uk/Topics/Statistics/Browse/Agriculture-Fisheries", "description": "1983-2009 | hub/id/119-44310", "format": ""}]}' -H "Authorization: d6c3349a-6ccf-45ef-88d4-a8e59a574bf2"
-
-
-
--- a/doc/api/3/index.rst Fri Jul 29 10:48:47 2011 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,18 +0,0 @@
-CKAN API Version 3
-==================
-
-.. toctree::
- :hidden:
- :maxdepth: 1
-
-.. include:: overview.rst.inc
-
-.. include:: model/index.rst.inc
-
-.. include:: search/index.rst.inc
-
-.. include:: status.rst.inc
-
-.. include:: example.rst.inc
-
-
--- a/doc/api/3/model/formats.rst.inc Fri Jul 29 10:48:47 2011 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,70 +0,0 @@
-Model Formats
-----------------------
-
-Here are the data formats for the Model API.
-
-+-----------------+------------------------------------------------------------+
-| Name | Format |
-+=================+============================================================+
-| Package-List | [ Id-String, Id-String, Id-String, ... ] |
-+-----------------+------------------------------------------------------------+
-| Package | { name: Name-String, title: String, version: String, |
-| | url: String, resources: [ Resource, Resource, ...], |
-| | author: String, author_email: String, |
-| | maintainer: String, maintainer_email: String, |
-| | license_id: String, tags: Tag-List, notes: String, |
-| | extras: { Name-String: String, ... } } |
-| | See note below on additional fields upon GET of a package. |
-+-----------------+------------------------------------------------------------+
-| Group-List | [ Id-String, Id-String, Id-String, ... ] |
-+-----------------+------------------------------------------------------------+
-| Group | { name: Name-String, title: String, description: String, |
-| | packages: Package-List } |
-+-----------------+------------------------------------------------------------+
-| Tag-List | [ Name-String, Name-String, Name-String, ... ] |
-+-----------------+------------------------------------------------------------+
-| Tag | { name: Name-String } |
-+-----------------+------------------------------------------------------------+
-| Resource | { url: String, format: String, description: String, |
-| | hash: String } |
-+-----------------+------------------------------------------------------------+
-| Rating | { package: Name-String, rating: int } |
-+-----------------+------------------------------------------------------------+
-|Pkg-Relationships| [ Pkg-Relationship, Pkg-Relationship, ... ] |
-+-----------------+------------------------------------------------------------+
-| Pkg-Relationship| { subject: Package-Name-String, |
-| | object: Package-Name-String, type: Relationship-Type, |
-| | comment: String } |
-+-----------------+------------------------------------------------------------+
-|Relationship-Type| One of: 'depends_on', 'dependency_of', |
-| | 'derives_from', 'has_derivation', |
-| | 'child_of', 'parent_of'. |
-+-----------------+------------------------------------------------------------+
-| Revision | { id: Uuid, message: String, author: String, |
-| | timestamp: Date-Time, packages: Package-List } |
-+-----------------+------------------------------------------------------------+
-| License-List | [ License, License, License, ... ] |
-+-----------------+------------------------------------------------------------+
-| License | { id: Name-String, title: String, is_okd_compliant: |
-| | Boolean, is_osi_compliant: Boolean, tags: Tag-List, |
-| | family: String, url: String, maintainer: String, |
-| | date_created: Date-Time, status: String } |
-+-----------------+------------------------------------------------------------+
-| Name-String | An alphanumeric string. |
-+-----------------+------------------------------------------------------------+
-
-To send request data, create a simple data structure, then convert it to a JSON string, then percent-encode the JSON string, then send it as the request body.
-
-Response data will be in the response body.
-
-Notes:
-
- * When you update an object, fields that you don't supply will remain as they were before.
-
- * To delete an 'extra' key-value pair, supply the key with a None value.
-
- * When you read a package then some additional information is supplied that cannot current be adjusted throught the CKAN API. This includes info on Package Relationship ('relationships'), Group membership ('groups'), ratings ('ratings_average' and 'ratings_count') and Package ID ('id'). This is purely a convenience for clients, and only forms part of the Package on GET.
-
-
-
-
--- a/doc/api/3/model/index.rst.inc Fri Jul 29 10:48:47 2011 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,14 +0,0 @@
-Model API
----------
-
-Model resources are available at published locations. They are represented with
-a variety of data formats. Each resource location supports a number of methods.
-
-The data formats of the requests and the responses are defined below.
-
-.. include:: resources.rst.inc
-
-.. include:: methods.rst.inc
-
-.. include:: formats.rst.inc
-
--- a/doc/api/3/model/methods.rst.inc Fri Jul 29 10:48:47 2011 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,49 +0,0 @@
-Model Methods
-~~~~~~~~~~~~~
-
-Here are the methods of the Model API.
-
-+-------------------------------+--------+------------------+-------------------+
-| Resource | Method | Request | Response |
-+===============================+========+==================+===================+
-| Package Register | GET | | Package-List |
-+-------------------------------+--------+------------------+-------------------+
-| Package Register | POST | Package | |
-+-------------------------------+--------+------------------+-------------------+
-| Package Entity | GET | | Package |
-+-------------------------------+--------+------------------+-------------------+
-| Package Entity | PUT | Package | |
-+-------------------------------+--------+------------------+-------------------+
-| Group Register | GET | | Group-List |
-+-------------------------------+--------+------------------+-------------------+
-| Group Register | POST | Group | |
-+-------------------------------+--------+------------------+-------------------+
-| Group Entity | GET | | Group |
-+-------------------------------+--------+------------------+-------------------+
-| Group Entity | PUT | Group | |
-+-------------------------------+--------+------------------+-------------------+
-| Tag Register | GET | | Tag-List |
-+-------------------------------+--------+------------------+-------------------+
-| Tag Entity | GET | | Package-List |
-+-------------------------------+--------+------------------+-------------------+
-| Rating Register | POST | Rating | |
-+-------------------------------+--------+------------------+-------------------+
-| Rating Entity | GET | | Rating |
-+-------------------------------+--------+------------------+-------------------+
-| Package Relationships Register| GET | | Pkg-Relationships |
-+-------------------------------+--------+------------------+-------------------+
-| Package Relationship Entity | GET | | Pkg-Relationship |
-+-------------------------------+--------+------------------+-------------------+
-| Package Relationship Entity | PUT | Pkg-Relationship | |
-+-------------------------------+--------+------------------+-------------------+
-| Revision Entity | GET | | Revision |
-+-------------------------------+--------+------------------+-------------------+
-| License List | GET | | License-List |
-+-------------------------------+--------+------------------+-------------------+
-
-* PUT operations may instead use the HTTP POST method.
-
-* POSTing data to a register resource will create a new entity, whilst PUT/POSTing data to an entity resource will update an existing entity.
-
-
-
--- a/doc/api/3/model/resources.rst.inc Fri Jul 29 10:48:47 2011 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,42 +0,0 @@
-Model Resources
-~~~~~~~~~~~~~~~
-
-Here are the resources of the Model API.
-
-+--------------------------------+-------------------------------------------------------------------+
-| Resource | Location |
-+================================+===================================================================+
-| Package Register | ``/api/rest/package`` |
-+--------------------------------+-------------------------------------------------------------------+
-| Package Entity | ``/api/rest/package/PACKAGE-REF`` |
-+--------------------------------+-------------------------------------------------------------------+
-| Group Register | ``/api/rest/group`` |
-+--------------------------------+-------------------------------------------------------------------+
-| Group Entity | ``/api/rest/group/GROUP-NAME`` |
-+--------------------------------+-------------------------------------------------------------------+
-| Tag Register | ``/api/rest/tag`` |
-+--------------------------------+-------------------------------------------------------------------+
-| Tag Entity | ``/api/rest/tag/TAG-NAME`` |
-+--------------------------------+-------------------------------------------------------------------+
-| Rating Register | ``/api/rest/rating`` |
-+--------------------------------+-------------------------------------------------------------------+
-| Rating Entity | ``/api/rest/rating/PACKAGE-REF`` |
-+--------------------------------+-------------------------------------------------------------------+
-| Package Relationships Register | ``/api/rest/package/PACKAGE-REF/relationships`` |
-+--------------------------------+-------------------------------------------------------------------+
-| Package Relationships Register | ``/api/rest/package/PACKAGE-REF/relationships/PACKAGE-REF`` |
-+--------------------------------+-------------------------------------------------------------------+
-| Package Relationship Entity | ``/api/rest/package/PACKAGE-REF/RELATIONSHIP-TYPE/PACKAGE-REF`` |
-+--------------------------------+-------------------------------------------------------------------+
-| Revision Register | ``/api/rest/revision`` |
-+--------------------------------+-------------------------------------------------------------------+
-| Revision Entity | ``/api/rest/revision/REVISION-ID`` |
-+--------------------------------+-------------------------------------------------------------------+
-| License List | ``/api/rest/licenses`` |
-+--------------------------------+-------------------------------------------------------------------+
-
-Possible values for PACKAGE-REF are the package id, or the current package name.
-
-Possible values for RELATIONSHIP-TYPE are described in the Relationship-Type data format.
-
-
--- a/doc/api/3/overview.rst.inc Fri Jul 29 10:48:47 2011 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,12 +0,0 @@
-API Overview
--------------
-
-The CKAN API is separated into three parts:
-
-* `Model API`_
-* `Search API`_
-
-The CKAN API follows the RESTful (Representational State Transfer)
-style. Published resources are separated both from the methods supported by
-the resources, and from the data formats and status codes used by the methods.
-
--- a/doc/api/3/search/formats.rst.inc Fri Jul 29 10:48:47 2011 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,127 +0,0 @@
-Search Formats
-~~~~~~~~~~~~~~~~~~~
-
-Here are the data formats for the Search API.
-
-+-------------------------+------------------------------------------------------------+
-| Name | Format |
-+=========================+============================================================+
-| Package-Search-Params | { Param-Key: Param-Value, Param-Key: Param-Value, ... } |
-| Resource-Search-Params | See below for full details of search parameters across the |
-| Revision-Search-Params | various domain objects. |
-+-------------------------+------------------------------------------------------------+
-| Package-Search-Response | { count: Count-int, results: [Package, Package, ... ] } |
-+-------------------------+------------------------------------------------------------+
-| Resource-Search-Response| { count: Count-int, results: [Resource, Resource, ... ] } |
-+-------------------------+------------------------------------------------------------+
-| Revision-List | [ Revision-Id, Revision-Id, Revision-Id, ... ] |
-| | NB: Ordered with youngest revision first |
-+-------------------------+------------------------------------------------------------+
-| Tag-Count-List | [ [Name-String, Integer], [Name-String, Integer], ... ] |
-+-------------------------+------------------------------------------------------------+
-
-The ``Package`` and ``Revision`` data formats are as defined in `Model Formats`_.
-
-
-Package Search Parameters
-""""""""""""""""""""""""""
-
-+-----------------------+---------------+----------------------------------+----------------------------------+
-| Param-Key | Param-Value | Example | Notes |
-+=======================+===============+==================================+==================================+
-| q | Search-String || q=geodata | Criteria to search the package |
-| | || q=government+sweden | fields for. URL-encoded search |
-| | || q=%22drug%20abuse%22 | text. (You can also concatenate |
-| | | | words with a '+' symbol in a |
-| | | | URL.) Search results must contain|
-| | | | all the specified words. |
-+-----------------------+---------------+----------------------------------+----------------------------------+
-| qjson | JSON encoded | ['q':'geodata'] | All search parameters can be |
-| | options | | json-encoded and supplied to this|
-| | | | parameter as a more flexible |
-| | | | alternative in GET requests. |
-+-----------------------+---------------+----------------------------------+----------------------------------+
-|title, | Search-String | title=uk&tags=health+census | Search a particular a field. Note|
-|tags, notes, groups, | | | that the latter fields mentioned |
-|author, maintainer, | | | here are in the 'extra' fields. |
-|update_frequency, | | | |
-|geographic_granularity,| | | |
-|geographic_coverage, | | | |
-|temporal_granularity, | | | |
-|temporal_coverage, | | | |
-|national_statistic, | | | |
-|categories, | | | |
-|precision, | | | |
-|department, agency, | | | |
-|external_reference | | | |
-+-----------------------+---------------+----------------------------------+----------------------------------+
-| order_by | field-name | order_by=name | Specify either rank or the field |
-| | (default=rank)| | to sort the results by |
-+-----------------------+---------------+----------------------------------+----------------------------------+
-| offset, limit | result-int | offset=40&limit=20 | Pagination options. Offset is the|
-| | (defaults: | | number of the first result and |
-| | offset=0, | | limit is the number of results to|
-| | limit=20) | | return. |
-+-----------------------+---------------+----------------------------------+----------------------------------+
-| all_fields | 0 (default) | all_fields=1 | Each matching search result is |
-| | or 1 | | given as either a package name |
-| | | | (0) or the full package record |
-| | | | (1). |
-+-----------------------+---------------+----------------------------------+----------------------------------+
-| filter_by_openness | 0 (default) | filter_by_openness=1 | Filters results by ones which are|
-| | or 1 | | open. |
-+-----------------------+---------------+----------------------------------+----------------------------------+
-|filter_by_downloadbable| 0 (default) | filter_by_downloadable=1 | Filters results by ones which |
-| | or 1 | | have at least one resource URL. |
-+-----------------------+---------------+----------------------------------+----------------------------------+
-
-
-Resource Search Parameters
-""""""""""""""""""""""""""
-
-+-----------------------+---------------+-----------------------------------------+----------------------------------+
-| Param-Key | Param-Value | Example | Notes |
-+=======================+===============+=========================================+==================================+
-| url, format, | Search-String || url=statistics.org | Criteria to search the package |
-| description | || format=xls | fields for. URL-encoded search |
-| | || description=Research+Institute | text. This search string must be |
-| | | | found somewhere within the field |
-| | | | to match. |
-| | | | Case insensitive. |
-+-----------------------+---------------+-----------------------------------------+----------------------------------+
-| qjson | JSON encoded | ['url':'www.statistics.org'] | All search parameters can be |
-| | options | | json-encoded and supplied to this|
-| | | | parameter as a more flexible |
-| | | | alternative in GET requests. |
-+-----------------------+---------------+-----------------------------------------+----------------------------------+
-| hash | Search-String |hash=b0d7c260-35d4-42ab-9e3d-c1f4db9bc2f0| Searches for an match of the |
-| | | | hash field. An exact match or |
-| | | | match up to the length of the |
-| | | | hash given. |
-+-----------------------+---------------+-----------------------------------------+----------------------------------+
-| all_fields | 0 (default) | all_fields=1 | Each matching search result is |
-| | or 1 | | given as either an ID (0) or the |
-| | | | full resource record |
-+-----------------------+---------------+-----------------------------------------+----------------------------------+
-| offset, limit | result-int | offset=40&limit=20 | Pagination options. Offset is the|
-| | (defaults: | | number of the first result and |
-| | offset=0, | | limit is the number of results to|
-| | limit=20) | | return. |
-+-----------------------+---------------+-----------------------------------------+----------------------------------+
-
-
-Revision Search Parameters
-""""""""""""""""""""""""""
-
-+-----------------------+---------------+-----------------------------------------------------+----------------------------------+
-| Param-Key | Param-Value | Example | Notes |
-+=======================+===============+=====================================================+==================================+
-| since_time | Date-Time | since_time=2010-05-05T19:42:45.854533 | The time can be less precisely |
-| | | | stated (e.g 2010-05-05). |
-+-----------------------+---------------+-----------------------------------------------------+----------------------------------+
-| since_id | Uuid | since_id=6c9f32ef-1f93-4b2f-891b-fd01924ebe08 | The stated id will not be |
-| | | | included in the results. |
-+-----------------------+---------------+-----------------------------------------------------+----------------------------------+
-
-
-
--- a/doc/api/3/search/index.rst.inc Fri Jul 29 10:48:47 2011 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,9 +0,0 @@
-Search API
----------------
-
-.. include:: resources.rst.inc
-
-.. include:: methods.rst.inc
-
-.. include:: formats.rst.inc
-
--- a/doc/api/3/search/methods.rst.inc Fri Jul 29 10:48:47 2011 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,22 +0,0 @@
-Search Methods
-~~~~~~~~~~~~~~
-
-Here are the methods of the Search API.
-
-+-------------------------------+--------+------------------------+--------------------------+
-| Resource | Method | Request | Response |
-+===============================+========+========================+==========================+
-| Package Search | POST | Package-Search-Params | Package-Search-Response |
-+-------------------------------+--------+------------------------+--------------------------+
-| Resource Search | POST | Resource-Search-Params | Resource-Search-Response |
-+-------------------------------+--------+------------------------+--------------------------+
-| Revision Search | POST | Revision-Search-Params | Revision-List |
-+-------------------------------+--------+------------------------+--------------------------+
-| Tag Counts | GET | | Tag-Count-List |
-+-------------------------------+--------+------------------------+--------------------------+
-
-It is also possible to supply the search parameters in the URL of a GET request,
-for example ``/api/search/package?q=geodata&allfields=1``.
-
-
-
--- a/doc/api/3/search/resources.rst.inc Fri Jul 29 10:48:47 2011 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,19 +0,0 @@
-Search Resources
-~~~~~~~~~~~~~~~~
-
-Here are the published resources of the Search API.
-
-+---------------------------+--------------------------+
-| Resource | Location |
-+===========================+==========================+
-| Package Search | ``/api/search/package`` |
-+---------------------------+--------------------------+
-| Resource Search | ``/api/search/resource`` |
-+---------------------------+--------------------------+
-| Revision Search | ``/api/search/revision`` |
-+---------------------------+--------------------------+
-| Tag Counts | ``/api/tag_counts`` |
-+---------------------------+--------------------------+
-
-See below for more information about package and revision search parameters.
-
--- a/doc/api/3/status.rst.inc Fri Jul 29 10:48:47 2011 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,18 +0,0 @@
-Status Codes
-------------
-
-Standard HTTP status codes are used to signal method outcomes.
-
-===== =====
-Code Name
-===== =====
-200 OK
-301 Moved Permanently
-400 Bad Request
-403 Not Authorized
-404 Not Found
-409 Conflict (e.g. name already exists)
-500 Service Error
-===== =====
-
-
--- a/doc/api/bottom.rst.inc Fri Jul 29 10:48:47 2011 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,3 +0,0 @@
-.. include:: keys.rst.inc
-.. include:: status.rst.inc
-.. include:: jsonp.rst.inc
--- a/doc/api/clients.rst.inc Fri Jul 29 10:48:47 2011 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,7 +0,0 @@
-Code Modules for Client Applications
--------------------------------------
-
-There are also some code modules (Python, PHP, Drupal, Perl etc.) that provide
-convenient wrappers around much of the CKAN API. For full details of these,
-please consult http://wiki.ckan.net/API
-
--- a/doc/api/example.rst.inc Fri Jul 29 10:48:47 2011 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,43 +0,0 @@
-Example of Usage
-----------------
-
-Let's say you're using ckan.net and want a list of all the packages. If you GET
-`<http://ckan.net/api/rest/package>`_ then it will return the list of the package
-names in JSON format::
-
-["2000-us-census-rdf", "32000-naples-florida-businesses-kml", "aaoe-87", "acawiki", "adb-sdbs", "addgene", "advances-in-dental-research", ... ]
-
-There are several ways you might access this URL:
-
-* simply put this URL into your web browser and save the resulting text file
-
-* you could use a command-line program such as `curl` or `wget`
-
-* you could write a program that uses an http library
-
-* use the Python library `CKAN Client <http://pypi.python.org/pypi/ckanclient>`_
-
-* use command-line tool `Datapkg <http://packages.python.org/datapkg/>`_. It manages datasets in a similar way as getting software packages with `apt-get` or `CPAN`.
-
-You could search for packages to do with 'open street map' like this: `<http://ckan.net/api/search/package?q=open+street+map>`_ returning::
-
-{"count": 4, "results": ["uk-naptan-osm", "osm-uk", "osm", "naptan"]}
-
-You can see the full record for the `osm` package in JSON format with this: `<http://ckan.net/api/rest/package/osm>`_ which returns::
-
-{"id": "a3dd8f64-9078-4f04-845c-e3f047125028", "name": "osm", "title": "Open Street Map", "version": null, "url": "http://www.openstreetmap.org/", ... }
-
-You might add a tag by a PUT to ``http://ckan.net/api/rest/package/osm`` with this data::
-
-{"tags": ["navigation", "openstreetmap", "map", "geo", "geodata", "xml", "publicdomain", "osm", "my-new-tag"]}
-
-Here we use `curl` to create a new package (you'll need your own :doc:`API Key <api/version2>` to try this)::
-
-$ curl http://test.ckan.net/api/rest/package -d '{"name":"test", "title":"Test package"}' -H "Authorization: 474d34e4-b710-4b77-b89f-2e909c336b91"
-
-And we create an example package with some government data::
-
-$ curl http://test.ckan.net/api/rest/package -d '{"name": "abstract_of_scottish_agricultural_statistics", "title": "Abstract of Scottish Agricultural Statistics", "version": null, "url": null, "author": "Scottish Government", "author_email": null, "maintainer": null, "maintainer_email": null, "notes": "A long term series of all the main agriculture census items collected in the June census.\n\nSource agency: Scottish Government\n\nDesignation: National Statistics\n\nLanguage: English\n\nAlternative title: Abstract of Scottish Agricultural Statistics", "license_id": "ukcrown-withrights", "tags": ["farm-outputs", "environment", "agriculture", "farming", "agriculture-and-environment"], "extras": {"geographic_coverage": "010000: Scotland", "geographical_granularity": "Country", "external_reference": "ONSHUB", "temporal_granularity": "", "date_updated": "", "agency": "", "precision": "", "temporal_coverage_to": "", "temporal_coverage_from": "", "national_statistic": "yes", "import_source": "ONS-ons_data_50_days_to_2010-05-04", "department": "Scottish Government", "update_frequency": "", "date_released": "2010-03-17", "categories": "Agriculture and Environment"}, "resources": [{"url": "http://www.scotland.gov.uk/Topics/Statistics/Browse/Agriculture-Fisheries", "description": "1982-2008 | hub/id/119-33192", "format": ""}, {"url": "http://www.scotland.gov.uk/Topics/Statistics/Browse/Agriculture-Fisheries", "description": "1982-2007 | hub/id/119-34917", "format": ""}, {"url": "http://www.scotland.gov.uk/Topics/Statistics/Browse/Agriculture-Fisheries", "description": "1983-2009 | hub/id/119-44310", "format": ""}]}' -H "Authorization: d6c3349a-6ccf-45ef-88d4-a8e59a574bf2"
-
-
-
--- a/doc/api/form_resources.rst.inc Fri Jul 29 10:48:47 2011 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,9 +0,0 @@
-Form Resources
-~~~~~~~~~~~~~~
-
-Here are the resources of the Form API.
-
-.. include:: form_resources_table.rst.inc
-
-Possible values for PACKAGE-REF are the package id, or the current package name.
-
--- a/doc/api/howtouse.rst.inc Fri Jul 29 10:48:47 2011 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,15 +0,0 @@
-Using the API
--------------
-
-To send request data, create a simple data structure, then convert it to a JSON string, then percent-encode the JSON string, then send it as the request body. Response data will be in the response body.
-
-If using curl, the default Content-Type header will be ``application/x-www-form-urlencoded`` and the JSON string gets sent as a single parameter key. However Javascript libraries tend to set Content-Type to be ``application/json`` and the JSON string is the body to the POST. The latter content became acceptable from CKAN version 1.4.2.
-
-Notes:
-
- * When you update an object, fields that you don't supply will remain as they were before.
-
- * To delete an 'extra' key-value pair, supply the key with a None value.
-
- * When you read a package then some additional information is supplied that cannot current be adjusted throught the CKAN API. This includes info on Package Relationship ('relationships'), Group membership ('groups'), ratings ('ratings_average' and 'ratings_count') and Package ID ('id'). This is purely a convenience for clients, and only forms part of the Package on GET.
-
--- a/doc/api/interfaces1.rst.inc Fri Jul 29 10:48:47 2011 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,9 +0,0 @@
-Interfaces
-----------
-
-The |site| |api| |version| is separated into three parts.
-
-* `Model API`_
-* `Search API`_
-
-The resources, methods, and data formats of each are described below.
--- a/doc/api/interfaces2.rst.inc Fri Jul 29 10:48:47 2011 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,10 +0,0 @@
-Interfaces
-----------
-
-The |site| |api| |version| is separated into three parts.
-
-* `Model API`_
-* `Search API`_
-* `Util API`_
-
-The resources, methods, and data formats of each are described below.
--- a/doc/api/jsonp.rst.inc Fri Jul 29 10:48:47 2011 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,17 +0,0 @@
-JSONP formatted responses
--------------------------
-
-To cater for scripts from other sites that wish to access the API, the data can be returned in JSONP format, where the JSON data is 'padded' with a function call. The function is named in the 'callback' parameter.
-
-Example normal request::
-
- GET /api/rest/package/pollution_stats
- returns: {"name": "pollution_stats", ... }
-
-but now with the callback parameter::
-
- GET /api/rest/package/pollution_stats?callback=jsoncallback
- returns: jsoncallback({"name": "pollution_stats", ... });
-
-This parameter can apply to all GET requests in the API.
-
--- a/doc/api/keys.rst.inc Fri Jul 29 10:48:47 2011 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,35 +0,0 @@
-API Keys
---------
-
-You will need to supply an API Key for certain requests to the CKAN API:
-
-* For any action which makes a change to a resource (i.e. all POST methods on register resources, and PUT/POST methods on entity resources).
-
-* If the particular resource's authorization set-up is not open to
- visitors for the action.
-
-To obtain your API key:
-
-1. Log-in to the particular CKAN website: /user/login
-
-2. The user page has a link to the API Key: /user/apikey
-
-The key should be passed in the API request header:
-
-================= =====
-Header Example value
-================= =====
-Authorization fde34a3c-b716-4c39-8dc4-881ba115c6d4
-================= =====
-
-If requests that are required to be authorized are not sent with a
-valid Authorization header, for example the user associated with the
-key is not authorized for the operation, or the header is somehow malformed,
-then the requested operation will not be carried out and the CKAN API will
-respond with status code 403.
-
-For more information about HTTP Authorization header, please refer to section
-14.8 of `RFC 2616 <http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.8>`_.
-
-
-
--- a/doc/api/location.rst.inc Fri Jul 29 10:48:47 2011 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,13 +0,0 @@
-Locators
---------
-
-The locator for a given resource can be formed by appending
-the relative path for that resource to the API locator.
-
- ``Resource Locator = API Locator + Resource Path``
-
-The API locator for the |site| |api| |version| is:
-
- |base_location|
-
-The relative paths for each resource are listed in the sections below.
--- a/doc/api/model_formats.rst.inc Fri Jul 29 10:48:47 2011 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,31 +0,0 @@
-Model Formats
-~~~~~~~~~~~~~
-
-Here are the data formats for the Model API.
-
-.. include:: model_formats_table.rst.inc
-
-.. |format-package-ref| replace:: Package-Id
-
-.. |format-package-register| replace:: [ |format-package-ref|, |format-package-ref|, |format-package-ref|, ... ]
-
-.. |format-package-entity| replace:: { id: Uuid, name: Name-String, title: String, version: String, url: String, resources: [ Resource, Resource, ...], author: String, author_email: String, maintainer: String, maintainer_email: String, license_id: String, tags: Tag-List, notes: String, extras: { Name-String: String, ... } }
-
-.. |format-group-ref| replace:: Group-Id
-
-.. |format-group-register| replace:: [ |format-group-ref|, |format-group-ref|, |format-group-ref|, ... ]
-
-.. |format-group-entity| replace:: { name: Name-String, title: String, description: String, packages: Package-List }
-
-
-To send request data, create the JSON-format string (encode in UTF8) put it in the request body and send it using PUT or POST.
-
-Response data will be in the response body in JSON format.
-
-Notes:
-
- * When you update an object, fields that you don't supply will remain as they were before.
-
- * To delete an 'extra' key-value pair, supply the key with JSON value: ``null``
-
- * When you read a package then some additional information is supplied that cannot current be adjusted throught the CKAN API. This includes info on Package Relationship ('relationships'), Group membership ('groups'), ratings ('ratings_average' and 'ratings_count'), full URL of the package in CKAN ('ckan_url') and Package ID ('id'). This is purely a convenience for clients, and only forms part of the Package on GET.
--- a/doc/api/model_formats_table.rst.inc Fri Jul 29 10:48:47 2011 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,49 +0,0 @@
-+--------------------+------------------------------------------------------------+
-| Name | Format |
-+====================+============================================================+
-| Package-List | |format-package-register| |
-+--------------------+------------------------------------------------------------+
-| Package | |format-package-entity| |
-| | See note below on additional fields upon GET of a package. |
-+--------------------+------------------------------------------------------------+
-| Group-List | |format-group-register| |
-+--------------------+------------------------------------------------------------+
-| Group | |format-group-entity| |
-+--------------------+------------------------------------------------------------+
-| Tag-List | [ Name-String, Name-String, Name-String, ... ] |
-+--------------------+------------------------------------------------------------+
-| Tag | { name: Name-String } |
-+--------------------+------------------------------------------------------------+
-| Resource | { url: String, format: String, description: String, |
-| | hash: String } |
-+--------------------+------------------------------------------------------------+
-| Rating | { package: Name-String, rating: int } |
-+--------------------+------------------------------------------------------------+
-| Pkg-Relationships | [ Pkg-Relationship, Pkg-Relationship, ... ] |
-+--------------------+------------------------------------------------------------+
-| Pkg-Relationship | { subject: Package-Name-String, |
-| | object: Package-Name-String, type: Relationship-Type, |
-| | comment: String } |
-+--------------------+------------------------------------------------------------+
-| Pkg-Revisions | [ Pkg-Revision, Pkg-Revision, Pkg-Revision, ... ] |
-+--------------------+------------------------------------------------------------+
-| Pkg-Revision | { id: Uuid, message: String, author: String, |
-| | timestamp: Date-Time } |
-+--------------------+------------------------------------------------------------+
-|Relationship-Type | One of: 'depends_on', 'dependency_of', |
-| | 'derives_from', 'has_derivation', |
-| | 'child_of', 'parent_of'. |
-+--------------------+------------------------------------------------------------+
-| Revision-List | [ revision_id, revision_id, revision_id, ... ] |
-+--------------------+------------------------------------------------------------+
-| Revision | { id: Uuid, message: String, author: String, |
-| | timestamp: Date-Time, packages: Package-List } |
-+--------------------+------------------------------------------------------------+
-| License-List | [ License, License, License, ... ] |
-+--------------------+------------------------------------------------------------+
-| License | { id: Name-String, title: String, is_okd_compliant: |
-| | Boolean, is_osi_compliant: Boolean, tags: Tag-List, |
-| | family: String, url: String, maintainer: String, |
-| | date_created: Date-Time, status: String } |
-+--------------------+------------------------------------------------------------+
-
--- a/doc/api/model_methods.rst.inc Fri Jul 29 10:48:47 2011 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,7 +0,0 @@
-Model Methods
-~~~~~~~~~~~~~
-
-Here are the methods of the Model API.
-
-.. include:: model_methods_table.rst.inc
-
--- a/doc/api/model_methods_table.rst.inc Fri Jul 29 10:48:47 2011 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,48 +0,0 @@
-+-------------------------------+--------+------------------+-------------------+
-| Resource | Method | Request | Response |
-+===============================+========+==================+===================+
-| Package Register | GET | | Package-List |
-+-------------------------------+--------+------------------+-------------------+
-| Package Register | POST | Package | |
-+-------------------------------+--------+------------------+-------------------+
-| Package Entity | GET | | Package |
-+-------------------------------+--------+------------------+-------------------+
-| Package Entity | PUT | Package | |
-+-------------------------------+--------+------------------+-------------------+
-| Group Register | GET | | Group-List |
-+-------------------------------+--------+------------------+-------------------+
-| Group Register | POST | Group | |
-+-------------------------------+--------+------------------+-------------------+
-| Group Entity | GET | | Group |
-+-------------------------------+--------+------------------+-------------------+
-| Group Entity | PUT | Group | |
-+-------------------------------+--------+------------------+-------------------+
-| Tag Register | GET | | Tag-List |
-+-------------------------------+--------+------------------+-------------------+
-| Tag Entity | GET | | Package-List |
-+-------------------------------+--------+------------------+-------------------+
-| Rating Register | POST | Rating | |
-+-------------------------------+--------+------------------+-------------------+
-| Rating Entity | GET | | Rating |
-+-------------------------------+--------+------------------+-------------------+
-| Package Relationships Register| GET | | Pkg-Relationships |
-+-------------------------------+--------+------------------+-------------------+
-| Package Relationship Entity | GET | | Pkg-Relationship |
-+-------------------------------+--------+------------------+-------------------+
-| Package Relationship Entity | PUT | Pkg-Relationship | |
-+-------------------------------+--------+------------------+-------------------+
-| Package\'s Revisions Entity | GET | | Pkg-Revisions |
-+-------------------------------+--------+------------------+-------------------+
-| Revision List | GET | | Revision-List |
-+-------------------------------+--------+------------------+-------------------+
-| Revision Entity | GET | | Revision |
-+-------------------------------+--------+------------------+-------------------+
-| License List | GET | | License-List |
-+-------------------------------+--------+------------------+-------------------+
-
-* POSTing data to a register resource will create a new entity.
-
-* PUT/POSTing data to an entity resource will update an existing entity.
-
-* PUT operations may instead use the HTTP POST method.
-
--- a/doc/api/model_preamble.rst.inc Fri Jul 29 10:48:47 2011 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,7 +0,0 @@
-Model resources are available at published locations. They are represented with
-a variety of data formats. Each resource location supports a number of methods.
-
-The data formats of the requests and the responses are defined below.
-
-
-
--- a/doc/api/model_resources.rst.inc Fri Jul 29 10:48:47 2011 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,7 +0,0 @@
-Model Resources
-~~~~~~~~~~~~~~~
-
-Here are the resources of the Model API.
-
-.. include:: model_resources_table.rst.inc
-
--- a/doc/api/model_resources_table.rst.inc Fri Jul 29 10:48:47 2011 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,40 +0,0 @@
-
-+--------------------------------+-------------------------------------------------------------------+
-| Model Resource | Location |
-+================================+===================================================================+
-| Package Register | ``/rest/package`` |
-+--------------------------------+-------------------------------------------------------------------+
-| Package Entity | ``/rest/package/PACKAGE-REF`` |
-+--------------------------------+-------------------------------------------------------------------+
-| Group Register | ``/rest/group`` |
-+--------------------------------+-------------------------------------------------------------------+
-| Group Entity | ``/rest/group/GROUP-REF`` |
-+--------------------------------+-------------------------------------------------------------------+
-| Tag Register | ``/rest/tag`` |
-+--------------------------------+-------------------------------------------------------------------+
-| Tag Entity | ``/rest/tag/TAG-NAME`` |
-+--------------------------------+-------------------------------------------------------------------+
-| Rating Register | ``/rest/rating`` |
-+--------------------------------+-------------------------------------------------------------------+
-| Package Relationships Register | ``/rest/package/PACKAGE-REF/relationships`` |
-+--------------------------------+-------------------------------------------------------------------+
-| Package Relationships Register | ``/rest/package/PACKAGE-REF/RELATIONSHIP-TYPE`` |
-+--------------------------------+-------------------------------------------------------------------+
-| Package Relationships Register | ``/rest/package/PACKAGE-REF/relationships/PACKAGE-REF`` |
-+--------------------------------+-------------------------------------------------------------------+
-| Package Relationship Entity | ``/rest/package/PACKAGE-REF/RELATIONSHIP-TYPE/PACKAGE-REF`` |
-+--------------------------------+-------------------------------------------------------------------+
-| Package\'s Revisions Entity | ``/rest/package/PACKAGE-REF/revisions`` |
-+--------------------------------+-------------------------------------------------------------------+
-| Revision Register | ``/rest/revision`` |
-+--------------------------------+-------------------------------------------------------------------+
-| Revision Entity | ``/rest/revision/REVISION-ID`` |
-+--------------------------------+-------------------------------------------------------------------+
-| License List | ``/rest/licenses`` |
-+--------------------------------+-------------------------------------------------------------------+
-
-Possible values for PACKAGE-REF are the package id, or the current package name.
-
-Possible values for RELATIONSHIP-TYPE are described in the Relationship-Type data format.
-
-
--- a/doc/api/overview.rst.inc Fri Jul 29 10:48:47 2011 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,16 +0,0 @@
-Overview
---------
-
-The |site| data catalog is not only available in a web browser, but also
-via its Application Programming Interface (API).
-
-The |api| can be used |usage| the catalog. This document describes the
-resource locations, data formats, and status codes which comprise the |site|
-|api|, so that anyone can create software applications that use the |api|
-service.
-
-The |site| |api| follows the RESTful (Representational State
-Transfer) style. Resource locations are separated both from the methods
-supported by the resources, and from the data formats and status codes
-used by the methods.
-
--- a/doc/api/purpose.rst.inc Fri Jul 29 10:48:47 2011 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,1 +0,0 @@
-This document describes |version| of the |main_doc|.
\ No newline at end of file
--- a/doc/api/search/index.rst.inc Fri Jul 29 10:48:47 2011 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,9 +0,0 @@
-Search API
----------------
-
-.. include:: resources.rst.inc
-
-.. include:: methods.rst.inc
-
-.. include:: formats.rst.inc
-
--- a/doc/api/search/package_params_table.rst.inc Fri Jul 29 10:48:47 2011 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,42 +0,0 @@
-+-----------------------+---------------+----------------------------------+----------------------------------+
-| Param-Key | Param-Value | Examples | Notes |
-+=======================+===============+==================================+==================================+
-| q | Search-String || q=geodata | Criteria to search the package |
-| | || q=government+sweden | fields for. URL-encoded search |
-| | || q=%22drug%20abuse%22 | text. (You can also concatenate |
-| | | | words with a '+' symbol in a |
-| | | | URL.) Search results must contain|
-| | | | all the specified words. |
-+-----------------------+---------------+----------------------------------+----------------------------------+
-| qjson | JSON encoded | ['q':'geodata'] | All search parameters can be |
-| | options | | json-encoded and supplied to this|
-| | | | parameter as a more flexible |
-| | | | alternative in GET requests. |
-+-----------------------+---------------+----------------------------------+----------------------------------+
-|title, | Search-String || title=uk&tags=health+census | Search in a particular a field. |
-|tags, notes, groups, | || department=environment | |
-|author, maintainer, | | | |
-|update_frequency, or | | | |
-|any 'extra' field name | | | |
-|e.g. department | | | |
-+-----------------------+---------------+----------------------------------+----------------------------------+
-| order_by | field-name | order_by=name | Specify either rank or the field |
-| | (default=rank)| | to sort the results by |
-+-----------------------+---------------+----------------------------------+----------------------------------+
-| offset, limit | result-int | offset=40&limit=20 | Pagination options. Offset is the|
-| | (defaults: | | number of the first result and |
-| | offset=0, | | limit is the number of results to|
-| | limit=20) | | return. |
-+-----------------------+---------------+----------------------------------+----------------------------------+
-| all_fields | 0 (default) | all_fields=1 | Each matching search result is |
-| | or 1 | | given as either a package name |
-| | | | (0) or the full package record |
-| | | | (1). |
-+-----------------------+---------------+----------------------------------+----------------------------------+
-| filter_by_openness | 0 (default) | filter_by_openness=1 | Filters results by ones which are|
-| | or 1 | | open. |
-+-----------------------+---------------+----------------------------------+----------------------------------+
-|filter_by_downloadbable| 0 (default) | filter_by_downloadable=1 | Filters results by ones which |
-| | or 1 | | have at least one resource URL. |
-+-----------------------+---------------+----------------------------------+----------------------------------+
-
--- a/doc/api/search/resource_params_table.rst.inc Fri Jul 29 10:48:47 2011 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,30 +0,0 @@
-+-----------------------+---------------+-----------------------------------------+----------------------------------+
-| Param-Key | Param-Value | Example | Notes |
-+=======================+===============+=========================================+==================================+
-| url, format, | Search-String || url=statistics.org | Criteria to search the package |
-| description | || format=xls | fields for. URL-encoded search |
-| | || description=Research+Institute | text. This search string must be |
-| | | | found somewhere within the field |
-| | | | to match. |
-| | | | Case insensitive. |
-+-----------------------+---------------+-----------------------------------------+----------------------------------+
-| qjson | JSON encoded | ['url':'www.statistics.org'] | All search parameters can be |
-| | options | | json-encoded and supplied to this|
-| | | | parameter as a more flexible |
-| | | | alternative in GET requests. |
-+-----------------------+---------------+-----------------------------------------+----------------------------------+
-| hash | Search-String |hash=b0d7c260-35d4-42ab-9e3d-c1f4db9bc2f0| Searches for an match of the |
-| | | | hash field. An exact match or |
-| | | | match up to the length of the |
-| | | | hash given. |
-+-----------------------+---------------+-----------------------------------------+----------------------------------+
-| all_fields | 0 (default) | all_fields=1 | Each matching search result is |
-| | or 1 | | given as either an ID (0) or the |
-| | | | full resource record |
-+-----------------------+---------------+-----------------------------------------+----------------------------------+
-| offset, limit | result-int | offset=40&limit=20 | Pagination options. Offset is the|
-| | (defaults: | | number of the first result and |
-| | offset=0, | | limit is the number of results to|
-| | limit=20) | | return. |
-+-----------------------+---------------+-----------------------------------------+----------------------------------+
-
--- a/doc/api/search/revision_params_table.rst.inc Fri Jul 29 10:48:47 2011 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,10 +0,0 @@
-+-----------------------+---------------+-----------------------------------------------------+----------------------------------+
-| Param-Key | Param-Value | Example | Notes |
-+=======================+===============+=====================================================+==================================+
-| since_time | Date-Time | since_time=2010-05-05T19:42:45.854533 | The time can be less precisely |
-| | | | stated (e.g 2010-05-05). |
-+-----------------------+---------------+-----------------------------------------------------+----------------------------------+
-| since_id | Uuid | since_id=6c9f32ef-1f93-4b2f-891b-fd01924ebe08 | The stated id will not be |
-| | | | included in the results. |
-+-----------------------+---------------+-----------------------------------------------------+----------------------------------+
-
--- a/doc/api/search_formats.rst.inc Fri Jul 29 10:48:47 2011 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,21 +0,0 @@
-Search Formats
-~~~~~~~~~~~~~~
-
-Here are the data formats for the Search API.
-
-.. include:: search_formats_table.rst.inc
-
-The ``Package`` and ``Revision`` data formats are as defined in `Model Formats`_.
-
-**Package Parameters**
-
-.. include:: search/package_params_table.rst.inc
-
-**Resource Parameters**
-
-.. include:: search/resource_params_table.rst.inc
-
-**Revision Parameters**
-
-.. include:: search/revision_params_table.rst.inc
-
--- a/doc/api/search_formats_table.rst.inc Fri Jul 29 10:48:47 2011 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,17 +0,0 @@
-+-------------------------+------------------------------------------------------------+
-| Name | Format |
-+=========================+============================================================+
-| Package-Search-Params | { Param-Key: Param-Value, Param-Key: Param-Value, ... } |
-| Resource-Search-Params | See below for full details of search parameters across the |
-| Revision-Search-Params | various domain objects. |
-+-------------------------+------------------------------------------------------------+
-| Package-Search-Response | { count: Count-int, results: [Package, Package, ... ] } |
-+-------------------------+------------------------------------------------------------+
-| Resource-Search-Response| { count: Count-int, results: [Resource, Resource, ... ] } |
-+-------------------------+------------------------------------------------------------+
-| Revision-List | [ Revision-Id, Revision-Id, Revision-Id, ... ] |
-| | NB: Ordered with youngest revision first |
-+-------------------------+------------------------------------------------------------+
-| Tag-Count-List | [ [Name-String, Integer], [Name-String, Integer], ... ] |
-+-------------------------+------------------------------------------------------------+
-
--- a/doc/api/search_methods.rst.inc Fri Jul 29 10:48:47 2011 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,12 +0,0 @@
-Search Methods
-~~~~~~~~~~~~~~
-
-Here are the methods of the Search API.
-
-.. include:: search_methods_table.rst.inc
-
-It is also possible to supply the search parameters in the URL of a GET request,
-for example ``/api/search/package?q=geodata&allfields=1``.
-
-
-
--- a/doc/api/search_methods_table.rst.inc Fri Jul 29 10:48:47 2011 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,12 +0,0 @@
-+-------------------------------+--------+------------------------+--------------------------+
-| Resource | Method | Request | Response |
-+===============================+========+========================+==========================+
-| Package Search | POST | Package-Search-Params | Package-Search-Response |
-+-------------------------------+--------+------------------------+--------------------------+
-| Resource Search | POST | Resource-Search-Params | Resource-Search-Response |
-+-------------------------------+--------+------------------------+--------------------------+
-| Revision Search | POST | Revision-Search-Params | Revision-List |
-+-------------------------------+--------+------------------------+--------------------------+
-| Tag Counts | GET | | Tag-Count-List |
-+-------------------------------+--------+------------------------+--------------------------+
-
--- a/doc/api/search_preamble.rst.inc Fri Jul 29 10:48:47 2011 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,4 +0,0 @@
-Search resources are available at published locations. They are represented with
-a variety of data formats. Each resource location supports a number of methods.
-
-The data formats of the requests and the responses are defined below.
--- a/doc/api/search_resources.rst.inc Fri Jul 29 10:48:47 2011 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,9 +0,0 @@
-Search Resources
-~~~~~~~~~~~~~~~~
-
-Here are the published resources of the Search API.
-
-.. include:: search_resources_table.rst.inc
-
-See below for more information about package and revision search parameters.
-
--- a/doc/api/search_resources_table.rst.inc Fri Jul 29 10:48:47 2011 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,13 +0,0 @@
-+---------------------------+--------------------------+
-| Search Resource | Location |
-+===========================+==========================+
-| Package Search | ``/search/package`` |
-+---------------------------+--------------------------+
-| Resource Search | ``/search/resource`` |
-+---------------------------+--------------------------+
-| Revision Search | ``/search/revision`` |
-+---------------------------+--------------------------+
-| Tag Counts | ``/tag_counts`` |
-+---------------------------+--------------------------+
-
-
--- a/doc/api/status.rst.inc Fri Jul 29 10:48:47 2011 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,18 +0,0 @@
-Status Codes
-------------
-
-Standard HTTP status codes are used to signal method outcomes.
-
-===== =====
-Code Name
-===== =====
-200 OK
-301 Moved Permanently
-400 Bad Request
-403 Not Authorized
-404 Not Found
-409 Conflict (e.g. name already exists)
-500 Service Error
-===== =====
-
-
--- a/doc/api/title.rst.inc Fri Jul 29 10:48:47 2011 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,3 +0,0 @@
-|site| |api| |version|
-======================
-
--- a/doc/api/version1.rst Fri Jul 29 10:48:47 2011 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,39 +0,0 @@
-.. toctree::
- :hidden:
-
-.. include:: title.rst.inc
-.. include:: purpose.rst.inc
-.. include:: warning.rst.inc
-.. include:: overview.rst.inc
-.. include:: interfaces1.rst.inc
-.. include:: location.rst.inc
-
-Model API
----------
-
-.. include:: model_preamble.rst.inc
-.. include:: model_resources.rst.inc
-.. include:: model_methods.rst.inc
-.. include:: model_formats.rst.inc
-
-Search API
-----------
-
-.. include:: search_preamble.rst.inc
-.. include:: search_resources.rst.inc
-.. include:: search_methods.rst.inc
-.. include:: search_formats.rst.inc
-
-.. include:: bottom.rst.inc
-
-.. |site| replace:: CKAN
-.. |api| replace:: API
-.. |version| replace:: Version 1
-.. |base_location| replace:: ``http://ckan.net/api/1``
-.. |main_doc| replace:: :doc:`../api`
-.. |usage| replace:: to view and change
-
-.. |format-package-ref| replace:: Package-Name
-.. |format-group-ref| replace:: Group-Name
-
-
--- a/doc/api/version2.rst Fri Jul 29 10:48:47 2011 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,107 +0,0 @@
-.. toctree::
- :hidden:
-
-.. include:: title.rst.inc
-.. include:: purpose.rst.inc
-.. include:: overview.rst.inc
-.. include:: interfaces2.rst.inc
-.. include:: location.rst.inc
-
-Model API
----------
-
-.. include:: model_preamble.rst.inc
-.. include:: model_resources.rst.inc
-.. include:: model_methods.rst.inc
-.. include:: model_formats.rst.inc
-
-Search API
-----------
-
-.. include:: search_preamble.rst.inc
-.. include:: search_resources.rst.inc
-.. include:: search_methods.rst.inc
-.. include:: search_formats.rst.inc
-
-.. include:: bottom.rst.inc
-
-Util API
---------
-
-Some of CKAN's client-side Javascript code makes calls to the CKAN API. For
-example, to generate a suggestion for a package name when adding a new package
-the following API call is made:
-
-::
-
- /api/2/util/package/create_slug?title=Package+1+Title+Typed+So+Far
-
-The return value is a JSON data structure:
-
-::
-
- {"valid": true, "name": "package_1_title_typed_so_far"}
-
-These are the keys returned:
-
-``valid``
-
- Can be ``True`` or ``False``. It is ``true`` when the title entered can be
- successfully turned into a package name and when that package name is not
- already being used. It is ``false`` otherwise.
-
-``name``
-
- The suggested name for the package, based on the title
-
-You can also add ``callback=callback`` to have the response returned as JSONP. eg:
-
-This URL:
-
-::
-
- /api/2/util/package/create_slug?title=Package+1+Title+Typed+So+Far&callback=callback
-
-Returns:
-
-::
-
- callback({"valid": true, "name": "package_1_title_typed_so_far"});
-
-In some CKAN deployments you may have the API deployed at a different domain
-from the main CKAN code. In these circumstances you'll need to add a new option
-to the config file to tell the new package form where it should make its API
-requests to:
-
-::
-
- ckan.api_url = http://api.example.com/
-
-
-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"}]}}
-
-
-
-.. |site| replace:: CKAN
-.. |api| replace:: API
-.. |version| replace:: Version 2
-.. |warning| replace:: This is the latest version of the API.
-.. |base_location| replace:: ``http://ckan.net/api/2``
-.. |main_doc| replace:: :doc:`../api`
-.. |usage| replace:: to view and change
-
-.. |format-package-ref| replace:: Package-Id
-.. |format-group-ref| replace:: Group-Id
-
--- a/doc/api/versions.rst.inc Fri Jul 29 10:48:47 2011 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,30 +0,0 @@
-.. |oldest_version| replace:: 1
-
-Versions
---------
-
-The |site| |api| is versioned, so that backwards incompatible changes can be
-introduced without removing existing support. A particular version of the API
-can be used by including its version number after the API location and before
-the resource location.
-
-If the API version is not included in the request, then the API will use the
-oldest supported version of the API to handle that request. The oldest supported
-version is currently |oldest_version|.
-
-
-Version 1
-~~~~~~~~~
-
-The |version_1_doc| is the original API. At first, package and group names were invariant, and were used in persistent references.
-
-Version 2
-~~~~~~~~~
-
-The |version_2_doc| is the latest API. Since edting the names of packages and groups is now possible, packages and groups are identified by their UUID in entity representations.
-
-.. Version 3
- ~~~~~~~~~
-
- The |version_3_doc| is the next CKAN API, and is currently unstable. Various resource locations are being changed to consolidate the interface design and help simplify the documentation and client implementations.
-
--- a/doc/api/warning.rst.inc Fri Jul 29 10:48:47 2011 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,1 +0,0 @@
-.. warning:: This version is now deprecated in favour of :doc:`version2`.
\ No newline at end of file
http://bitbucket.org/okfn/ckan/changeset/e5c98e246837/
changeset: e5c98e246837
user: dread
date: 2011-07-29 13:03:02
summary: [merge] from release-v1.4.3.
affected #: 49 files (28.0 KB)
--- a/doc/api.rst Fri Jul 29 10:49:26 2011 +0100
+++ b/doc/api.rst Fri Jul 29 12:03:02 2011 +0100
@@ -1,41 +1,537 @@
-.. |site| replace:: CKAN
-
-.. |api| replace:: API
-
-.. |base_location| replace:: ``http://ckan.net/api``
-
-.. |usage| replace:: to view and change
-
-.. |version_1_location| replace:: ``http://ckan.net/api/1``
-
-.. |version_2_location| replace:: ``http://ckan.net/api/2``
-
-.. |version_1_doc| replace:: :doc:`api/version1`
-
-.. |version_2_doc| replace:: :doc:`api/version2`
-
-.. #|version_3_doc| replace:: :doc:`api/version3`
-
.. index:: API
===========================
-Reference: The |site| |api|
+Reference: CKAN API
===========================
.. toctree::
:hidden:
:maxdepth: 1
-The |site| |api| presents the catalog of metadata behind |site|.
+The CKAN API provides programmatic access to the catalog of metadata stored in CKAN.
-.. note:: This section contains general information about the |site| API. If you are looking for API documentation, please see |version_2_doc|.
+Overview
+--------
-.. include:: api/overview.rst.inc
+The CKAN data catalog is not only available in a web browser, but also
+via its Application Programming Interface (API).
-.. include:: api/versions.rst.inc
+The API can be used to view and change the catalog. This document describes the
+resource locations, data formats, and status codes which comprise the CKAN
+API, so that anyone can create software applications that use the API
+service.
-.. include:: api/clients.rst.inc
+The CKAN API follows the RESTful (Representational State
+Transfer) style. Resource locations are separated both from the methods
+supported by the resources, and from the data formats and status codes
+used by the methods.
-.. include:: api/example.rst.inc
+Examples
+--------
+For a tutorial and examples of using the CKAN API, see: http://wiki.ckan.net/Using_the_API
+Code Modules for Client Applications
+-------------------------------------
+
+There are also some code modules (Python, PHP, Drupal, Perl etc.) that provide
+convenient wrappers around much of the CKAN API. For full details of these,
+please consult http://wiki.ckan.net/API
+
+Versions
+--------
+
+The CKAN API is versioned, so that backwards incompatible changes can be
+introduced without removing existing support. A particular version of the API
+can be used by including its version number after the API location and before
+the resource location.
+
+If the API version is not specified in the request, then the API will default to version 1.
+
+Versions 1 & 2
+~~~~~~~~~~~~~~
+
+These are very similar, but when the API returns a reference to an object, Version 1 API will return the Name of the object (e.g. "river-pollution") and Version 2 API will return the ID of the object (e.g. "a3dd8f64-9078-4f04-845c-e3f047125028").
+
+The reason for this is that Names can change, so to reliably refer to the same package every time, you will want to use the ID and therefore use API v2. Alternatively, many people prefer to deal with Names, so API v1 suits them.
+
+When making requests, you can call objects by either their Name or ID, interchangeably.
+
+The only exception for this is for Tag objects. Since Tag names are immutable, they are always referred to with their Name.
+
+
+API Details - Versions 1 & 2
+----------------------------
+
+Overview
+~~~~~~~~
+
+The CKAN data catalog is not only available in a web browser, but also
+via its Application Programming Interface (API).
+
+The API can be used to view and change the catalog. This document describes the
+resource locations, data formats, and status codes which comprise the CKAN
+API, so that anyone can create software applications that use the API
+service.
+
+The CKAN API follows the RESTful (Representational State
+Transfer) style. Resource locations are separated both from the methods
+supported by the resources, and from the data formats and status codes
+used by the methods.
+
+
+The CKAN API version 1 & 2 is separated into three parts.
+
+* `Model API`_
+* `Search API`_
+* `Util API`_
+
+The resources, methods, and data formats of each are described below.
+
+Locators
+~~~~~~~~
+
+The locator for a given resource can be formed by appending
+the relative path for that resource to the API locator.
+
+ ``Resource Locator = API Locator + Resource Path``
+
+The API locators for the CKAN APIs (by version) are:
+
+ * ``http://ckan.net/api`` (version 1)
+ * ``http://ckan.net/api/1`` (version 1)
+ * ``http://ckan.net/api/2`` (version 2)
+
+The relative paths for each resource are listed in the sections below.
+
+Model API
+~~~~~~~~~
+
+Model resources are available at published locations. They are represented with
+a variety of data formats. Each resource location supports a number of methods.
+
+The data formats of the requests and the responses are defined below.
+
+Model Resources
+```````````````
+
+Here are the resources of the Model API.
+
+
++--------------------------------+-------------------------------------------------------------------+
+| Model Resource | Location |
++================================+===================================================================+
+| Package Register | ``/rest/package`` |
++--------------------------------+-------------------------------------------------------------------+
+| Package Entity | ``/rest/package/PACKAGE-REF`` |
++--------------------------------+-------------------------------------------------------------------+
+| Group Register | ``/rest/group`` |
++--------------------------------+-------------------------------------------------------------------+
+| Group Entity | ``/rest/group/GROUP-REF`` |
++--------------------------------+-------------------------------------------------------------------+
+| Tag Register | ``/rest/tag`` |
++--------------------------------+-------------------------------------------------------------------+
+| Tag Entity | ``/rest/tag/TAG-NAME`` |
++--------------------------------+-------------------------------------------------------------------+
+| Rating Register | ``/rest/rating`` |
++--------------------------------+-------------------------------------------------------------------+
+| Package Relationships Register | ``/rest/package/PACKAGE-REF/relationships`` |
++--------------------------------+-------------------------------------------------------------------+
+| Package Relationships Register | ``/rest/package/PACKAGE-REF/RELATIONSHIP-TYPE`` |
++--------------------------------+-------------------------------------------------------------------+
+| Package Relationships Register | ``/rest/package/PACKAGE-REF/relationships/PACKAGE-REF`` |
++--------------------------------+-------------------------------------------------------------------+
+| Package Relationship Entity | ``/rest/package/PACKAGE-REF/RELATIONSHIP-TYPE/PACKAGE-REF`` |
++--------------------------------+-------------------------------------------------------------------+
+| Package\'s Revisions Entity | ``/rest/package/PACKAGE-REF/revisions`` |
++--------------------------------+-------------------------------------------------------------------+
+| Revision Register | ``/rest/revision`` |
++--------------------------------+-------------------------------------------------------------------+
+| Revision Entity | ``/rest/revision/REVISION-ID`` |
++--------------------------------+-------------------------------------------------------------------+
+| License List | ``/rest/licenses`` |
++--------------------------------+-------------------------------------------------------------------+
+
+Possible values for PACKAGE-REF are the package id, or the current package name.
+
+Possible values for RELATIONSHIP-TYPE are described in the Relationship-Type data format.
+
+
+Model Methods
+`````````````
+
+Here are the methods of the Model API.
+
++-------------------------------+--------+------------------+-------------------+
+| Resource | Method | Request | Response |
++===============================+========+==================+===================+
+| Package Register | GET | | Package-List |
++-------------------------------+--------+------------------+-------------------+
+| Package Register | POST | Package | |
++-------------------------------+--------+------------------+-------------------+
+| Package Entity | GET | | Package |
++-------------------------------+--------+------------------+-------------------+
+| Package Entity | PUT | Package | |
++-------------------------------+--------+------------------+-------------------+
+| Group Register | GET | | Group-List |
++-------------------------------+--------+------------------+-------------------+
+| Group Register | POST | Group | |
++-------------------------------+--------+------------------+-------------------+
+| Group Entity | GET | | Group |
++-------------------------------+--------+------------------+-------------------+
+| Group Entity | PUT | Group | |
++-------------------------------+--------+------------------+-------------------+
+| Tag Register | GET | | Tag-List |
++-------------------------------+--------+------------------+-------------------+
+| Tag Entity | GET | | Package-List |
++-------------------------------+--------+------------------+-------------------+
+| Rating Register | POST | Rating | |
++-------------------------------+--------+------------------+-------------------+
+| Rating Entity | GET | | Rating |
++-------------------------------+--------+------------------+-------------------+
+| Package Relationships Register| GET | | Pkg-Relationships |
++-------------------------------+--------+------------------+-------------------+
+| Package Relationship Entity | GET | | Pkg-Relationship |
++-------------------------------+--------+------------------+-------------------+
+| Package Relationship Entity | PUT | Pkg-Relationship | |
++-------------------------------+--------+------------------+-------------------+
+| Package\'s Revisions Entity | GET | | Pkg-Revisions |
++-------------------------------+--------+------------------+-------------------+
+| Revision List | GET | | Revision-List |
++-------------------------------+--------+------------------+-------------------+
+| Revision Entity | GET | | Revision |
++-------------------------------+--------+------------------+-------------------+
+| License List | GET | | License-List |
++-------------------------------+--------+------------------+-------------------+
+
+* POSTing data to a register resource will create a new entity.
+
+* PUT/POSTing data to an entity resource will update an existing entity.
+
+* PUT operations may instead use the HTTP POST method.
+
+Model Formats
+`````````````
+
+Here are the data formats for the Model API.
+
+.. |format-package-ref| replace:: Package-Ref
+
+.. |format-package-register| replace:: [ |format-package-ref|, |format-package-ref|, |format-package-ref|, ... ]
+
+.. |format-package-entity| replace:: { id: Uuid, name: Name-String, title: String, version: String, url: String, resources: [ Resource, Resource, ...], author: String, author_email: String, maintainer: String, maintainer_email: String, license_id: String, tags: Tag-List, notes: String, extras: { Name-String: String, ... } }
+
+.. |format-group-ref| replace:: Group-Ref
+
+.. |format-group-register| replace:: [ |format-group-ref|, |format-group-ref|, |format-group-ref|, ... ]
+
+.. |format-group-entity| replace:: { name: Name-String, title: String, description: String, packages: Package-List }
+
+
+To send request data, create the JSON-format string (encode in UTF8) put it in the request body and send it using PUT or POST.
+
+Response data will be in the response body in JSON format.
+
+Notes:
+
+ * When you update an object, fields that you don't supply will remain as they were before.
+
+ * To delete an 'extra' key-value pair, supply the key with JSON value: ``null``
+
+ * When you read a package then some additional information is supplied that cannot current be adjusted throught the CKAN API. This includes info on Package Relationship ('relationships'), Group membership ('groups'), ratings ('ratings_average' and 'ratings_count'), full URL of the package in CKAN ('ckan_url') and Package ID ('id'). This is purely a convenience for clients, and only forms part of the Package on GET.
+
+Search API
+~~~~~~~~~~
+
+Search resources are available at published locations. They are represented with
+a variety of data formats. Each resource location supports a number of methods.
+
+The data formats of the requests and the responses are defined below.
+
+Search Resources
+````````````````
+
+Here are the published resources of the Search API.
+
++---------------------------+--------------------------+
+| Search Resource | Location |
++===========================+==========================+
+| Package Search | ``/search/package`` |
++---------------------------+--------------------------+
+| Resource Search | ``/search/resource`` |
++---------------------------+--------------------------+
+| Revision Search | ``/search/revision`` |
++---------------------------+--------------------------+
+| Tag Counts | ``/tag_counts`` |
++---------------------------+--------------------------+
+
+See below for more information about package and revision search parameters.
+
+Search Methods
+``````````````
+
+Here are the methods of the Search API.
+
++-------------------------------+--------+------------------------+--------------------------+
+| Resource | Method | Request | Response |
++===============================+========+========================+==========================+
+| Package Search | POST | Package-Search-Params | Package-Search-Response |
++-------------------------------+--------+------------------------+--------------------------+
+| Resource Search | POST | Resource-Search-Params | Resource-Search-Response |
++-------------------------------+--------+------------------------+--------------------------+
+| Revision Search | POST | Revision-Search-Params | Revision-List |
++-------------------------------+--------+------------------------+--------------------------+
+| Tag Counts | GET | | Tag-Count-List |
++-------------------------------+--------+------------------------+--------------------------+
+
+It is also possible to supply the search parameters in the URL of a GET request,
+for example ``/api/search/package?q=geodata&allfields=1``.
+
+Search Formats
+``````````````
+
+Here are the data formats for the Search API.
+
++-------------------------+------------------------------------------------------------+
+| Name | Format |
++=========================+============================================================+
+| Package-Search-Params | { Param-Key: Param-Value, Param-Key: Param-Value, ... } |
+| Resource-Search-Params | See below for full details of search parameters across the |
+| Revision-Search-Params | various domain objects. |
++-------------------------+------------------------------------------------------------+
+| Package-Search-Response | { count: Count-int, results: [Package, Package, ... ] } |
++-------------------------+------------------------------------------------------------+
+| Resource-Search-Response| { count: Count-int, results: [Resource, Resource, ... ] } |
++-------------------------+------------------------------------------------------------+
+| Revision-List | [ Revision-Id, Revision-Id, Revision-Id, ... ] |
+| | NB: Ordered with youngest revision first |
++-------------------------+------------------------------------------------------------+
+| Tag-Count-List | [ [Name-String, Integer], [Name-String, Integer], ... ] |
++-------------------------+------------------------------------------------------------+
+
+The ``Package`` and ``Revision`` data formats are as defined in `Model Formats`_.
+
+**Package Parameters**
+
++-----------------------+---------------+----------------------------------+----------------------------------+
+| Param-Key | Param-Value | Examples | Notes |
++=======================+===============+==================================+==================================+
+| q | Search-String || q=geodata | Criteria to search the package |
+| | || q=government+sweden | fields for. URL-encoded search |
+| | || q=%22drug%20abuse%22 | text. (You can also concatenate |
+| | | | words with a '+' symbol in a |
+| | | | URL.) Search results must contain|
+| | | | all the specified words. |
++-----------------------+---------------+----------------------------------+----------------------------------+
+| qjson | JSON encoded | ['q':'geodata'] | All search parameters can be |
+| | options | | json-encoded and supplied to this|
+| | | | parameter as a more flexible |
+| | | | alternative in GET requests. |
++-----------------------+---------------+----------------------------------+----------------------------------+
+|title, | Search-String || title=uk&tags=health+census | Search in a particular a field. |
+|tags, notes, groups, | || department=environment | |
+|author, maintainer, | | | |
+|update_frequency, or | | | |
+|any 'extra' field name | | | |
+|e.g. department | | | |
++-----------------------+---------------+----------------------------------+----------------------------------+
+| order_by | field-name | order_by=name | Specify either rank or the field |
+| | (default=rank)| | to sort the results by |
++-----------------------+---------------+----------------------------------+----------------------------------+
+| offset, limit | result-int | offset=40&limit=20 | Pagination options. Offset is the|
+| | (defaults: | | number of the first result and |
+| | offset=0, | | limit is the number of results to|
+| | limit=20) | | return. |
++-----------------------+---------------+----------------------------------+----------------------------------+
+| all_fields | 0 (default) | all_fields=1 | Each matching search result is |
+| | or 1 | | given as either a package name |
+| | | | (0) or the full package record |
+| | | | (1). |
++-----------------------+---------------+----------------------------------+----------------------------------+
+| filter_by_openness | 0 (default) | filter_by_openness=1 | Filters results by ones which are|
+| | or 1 | | open. |
++-----------------------+---------------+----------------------------------+----------------------------------+
+|filter_by_downloadbable| 0 (default) | filter_by_downloadable=1 | Filters results by ones which |
+| | or 1 | | have at least one resource URL. |
++-----------------------+---------------+----------------------------------+----------------------------------+
+
+**Resource Parameters**
+
++-----------------------+---------------+-----------------------------------------+----------------------------------+
+| Param-Key | Param-Value | Example | Notes |
++=======================+===============+=========================================+==================================+
+| url, format, | Search-String || url=statistics.org | Criteria to search the package |
+| description | || format=xls | fields for. URL-encoded search |
+| | || description=Research+Institute | text. This search string must be |
+| | | | found somewhere within the field |
+| | | | to match. |
+| | | | Case insensitive. |
++-----------------------+---------------+-----------------------------------------+----------------------------------+
+| qjson | JSON encoded | ['url':'www.statistics.org'] | All search parameters can be |
+| | options | | json-encoded and supplied to this|
+| | | | parameter as a more flexible |
+| | | | alternative in GET requests. |
++-----------------------+---------------+-----------------------------------------+----------------------------------+
+| hash | Search-String |hash=b0d7c260-35d4-42ab-9e3d-c1f4db9bc2f0| Searches for an match of the |
+| | | | hash field. An exact match or |
+| | | | match up to the length of the |
+| | | | hash given. |
++-----------------------+---------------+-----------------------------------------+----------------------------------+
+| all_fields | 0 (default) | all_fields=1 | Each matching search result is |
+| | or 1 | | given as either an ID (0) or the |
+| | | | full resource record |
++-----------------------+---------------+-----------------------------------------+----------------------------------+
+| offset, limit | result-int | offset=40&limit=20 | Pagination options. Offset is the|
+| | (defaults: | | number of the first result and |
+| | offset=0, | | limit is the number of results to|
+| | limit=20) | | return. |
++-----------------------+---------------+-----------------------------------------+----------------------------------+
+
+**Revision Parameters**
+
++-----------------------+---------------+-----------------------------------------------------+----------------------------------+
+| Param-Key | Param-Value | Example | Notes |
++=======================+===============+=====================================================+==================================+
+| since_time | Date-Time | since_time=2010-05-05T19:42:45.854533 | The time can be less precisely |
+| | | | stated (e.g 2010-05-05). |
++-----------------------+---------------+-----------------------------------------------------+----------------------------------+
+| since_id | Uuid | since_id=6c9f32ef-1f93-4b2f-891b-fd01924ebe08 | The stated id will not be |
+| | | | included in the results. |
++-----------------------+---------------+-----------------------------------------------------+----------------------------------+
+
+API Keys
+~~~~~~~~
+
+You will need to supply an API Key for certain requests to the CKAN API:
+
+* For any action which makes a change to a resource (i.e. all POST methods on register resources, and PUT/POST methods on entity resources).
+
+* If the particular resource's authorization set-up is not open to
+ visitors for the action.
+
+To obtain your API key:
+
+1. Log-in to the particular CKAN website: /user/login
+
+2. The user page has a link to the API Key: /user/apikey
+
+The key should be passed in the API request header:
+
+================= =====
+Header Example value
+================= =====
+Authorization ``fde34a3c-b716-4c39-8dc4-881ba115c6d4``
+================= =====
+
+If requests that are required to be authorized are not sent with a
+valid Authorization header, for example the user associated with the
+key is not authorized for the operation, or the header is somehow malformed,
+then the requested operation will not be carried out and the CKAN API will
+respond with status code 403.
+
+For more information about HTTP Authorization header, please refer to section
+14.8 of `RFC 2616 <http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.8>`_.
+
+
+Status Codes
+~~~~~~~~~~~~
+
+Standard HTTP status codes are used to signal method outcomes.
+
+===== =====
+Code Name
+===== =====
+200 OK
+201 OK and new object created (referred to in the Location header)
+301 Moved Permanently
+400 Bad Request
+403 Not Authorized
+404 Not Found
+409 Conflict (e.g. name already exists)
+500 Service Error
+===== =====
+
+JSONP formatted responses
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To cater for scripts from other sites that wish to access the API, the data can be returned in JSONP format, where the JSON data is 'padded' with a function call. The function is named in the 'callback' parameter.
+
+Example normal request::
+
+ GET /api/rest/package/pollution_stats
+ returns: {"name": "pollution_stats", ... }
+
+but now with the callback parameter::
+
+ GET /api/rest/package/pollution_stats?callback=jsoncallback
+ returns: jsoncallback({"name": "pollution_stats", ... });
+
+This parameter can apply to all GET requests in the API.
+
+
+Util API
+~~~~~~~~
+
+Some of CKAN's client-side Javascript code makes calls to the CKAN API. For
+example, to generate a suggestion for a package name when adding a new package
+the following API call is made:
+
+::
+
+ /api/2/util/package/create_slug?title=Package+1+Title+Typed+So+Far
+
+The return value is a JSON data structure:
+
+::
+
+ {"valid": true, "name": "package_1_title_typed_so_far"}
+
+These are the keys returned:
+
+``valid``
+
+ Can be ``True`` or ``False``. It is ``true`` when the title entered can be
+ successfully turned into a package name and when that package name is not
+ already being used. It is ``false`` otherwise.
+
+``name``
+
+ The suggested name for the package, based on the title
+
+You can also add ``callback=callback`` to have the response returned as JSONP. eg:
+
+This URL:
+
+::
+
+ /api/2/util/package/create_slug?title=Package+1+Title+Typed+So+Far&callback=callback
+
+Returns:
+
+::
+
+ callback({"valid": true, "name": "package_1_title_typed_so_far"});
+
+In some CKAN deployments you may have the API deployed at a different domain
+from the main CKAN code. In these circumstances you'll need to add a new option
+to the config file to tell the new package form where it should make its API
+requests to:
+
+::
+
+ ckan.api_url = http://api.example.com/
+
+
+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"}]}}
--- a/doc/api/3/example.rst.inc Fri Jul 29 10:49:26 2011 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,43 +0,0 @@
-Example of Usage
-----------------
-
-Let's say you're using ckan.net and want a list of all the packages. If you GET
-`<http://ckan.net/api/rest/package>`_ then it will return the list of the package
-names in JSON format::
-
-["2000-us-census-rdf", "32000-naples-florida-businesses-kml", "aaoe-87", "acawiki", "adb-sdbs", "addgene", "advances-in-dental-research", ... ]
-
-There are several ways you might access this URL:
-
-* simply put this URL into your web browser and save the resulting text file
-
-* you could use a command-line program such as `curl` or `wget`
-
-* you could write a program that uses an http library
-
-* use the Python library `CKAN Client <http://pypi.python.org/pypi/ckanclient>`_
-
-* use command-line tool `Datapkg <http://packages.python.org/datapkg/>`_. It manages datasets in a similar way as getting software packages with `apt-get` or `CPAN`.
-
-You could search for packages to do with 'open street map' like this: `<http://ckan.net/api/search/package?q=open+street+map>`_ returning::
-
-{"count": 4, "results": ["uk-naptan-osm", "osm-uk", "osm", "naptan"]}
-
-You can see the full record for the `osm` package in JSON format with this: `<http://ckan.net/api/rest/package/osm>`_ which returns::
-
-{"id": "a3dd8f64-9078-4f04-845c-e3f047125028", "name": "osm", "title": "Open Street Map", "version": null, "url": "http://www.openstreetmap.org/", ... }
-
-You might add a tag by a PUT to ``http://ckan.net/api/rest/package/osm`` with this data::
-
-{"tags": ["navigation", "openstreetmap", "map", "geo", "geodata", "xml", "publicdomain", "osm", "my-new-tag"]}
-
-Here we use `curl` to create a new package::
-
-$ curl http://test.ckan.net/api/rest/package -d '{"name":"test", "title":"Test package"}' -H "Authorization: 474d34e4-b710-4b77-b89f-2e909c336b91"
-
-And we create an example package with some government data::
-
-$ curl http://test.ckan.net/api/rest/package -d '{"name": "abstract_of_scottish_agricultural_statistics", "title": "Abstract of Scottish Agricultural Statistics", "version": null, "url": null, "author": "Scottish Government", "author_email": null, "maintainer": null, "maintainer_email": null, "notes": "A long term series of all the main agriculture census items collected in the June census.\n\nSource agency: Scottish Government\n\nDesignation: National Statistics\n\nLanguage: English\n\nAlternative title: Abstract of Scottish Agricultural Statistics", "license_id": "ukcrown-withrights", "tags": ["farm-outputs", "environment", "agriculture", "farming", "agriculture-and-environment"], "extras": {"geographic_coverage": "010000: Scotland", "geographical_granularity": "Country", "external_reference": "ONSHUB", "temporal_granularity": "", "date_updated": "", "agency": "", "precision": "", "temporal_coverage_to": "", "temporal_coverage_from": "", "national_statistic": "yes", "import_source": "ONS-ons_data_50_days_to_2010-05-04", "department": "Scottish Government", "update_frequency": "", "date_released": "2010-03-17", "categories": "Agriculture and Environment"}, "resources": [{"url": "http://www.scotland.gov.uk/Topics/Statistics/Browse/Agriculture-Fisheries", "description": "1982-2008 | hub/id/119-33192", "format": ""}, {"url": "http://www.scotland.gov.uk/Topics/Statistics/Browse/Agriculture-Fisheries", "description": "1982-2007 | hub/id/119-34917", "format": ""}, {"url": "http://www.scotland.gov.uk/Topics/Statistics/Browse/Agriculture-Fisheries", "description": "1983-2009 | hub/id/119-44310", "format": ""}]}' -H "Authorization: d6c3349a-6ccf-45ef-88d4-a8e59a574bf2"
-
-
-
--- a/doc/api/3/index.rst Fri Jul 29 10:49:26 2011 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,18 +0,0 @@
-CKAN API Version 3
-==================
-
-.. toctree::
- :hidden:
- :maxdepth: 1
-
-.. include:: overview.rst.inc
-
-.. include:: model/index.rst.inc
-
-.. include:: search/index.rst.inc
-
-.. include:: status.rst.inc
-
-.. include:: example.rst.inc
-
-
--- a/doc/api/3/model/formats.rst.inc Fri Jul 29 10:49:26 2011 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,70 +0,0 @@
-Model Formats
-----------------------
-
-Here are the data formats for the Model API.
-
-+-----------------+------------------------------------------------------------+
-| Name | Format |
-+=================+============================================================+
-| Package-List | [ Id-String, Id-String, Id-String, ... ] |
-+-----------------+------------------------------------------------------------+
-| Package | { name: Name-String, title: String, version: String, |
-| | url: String, resources: [ Resource, Resource, ...], |
-| | author: String, author_email: String, |
-| | maintainer: String, maintainer_email: String, |
-| | license_id: String, tags: Tag-List, notes: String, |
-| | extras: { Name-String: String, ... } } |
-| | See note below on additional fields upon GET of a package. |
-+-----------------+------------------------------------------------------------+
-| Group-List | [ Id-String, Id-String, Id-String, ... ] |
-+-----------------+------------------------------------------------------------+
-| Group | { name: Name-String, title: String, description: String, |
-| | packages: Package-List } |
-+-----------------+------------------------------------------------------------+
-| Tag-List | [ Name-String, Name-String, Name-String, ... ] |
-+-----------------+------------------------------------------------------------+
-| Tag | { name: Name-String } |
-+-----------------+------------------------------------------------------------+
-| Resource | { url: String, format: String, description: String, |
-| | hash: String } |
-+-----------------+------------------------------------------------------------+
-| Rating | { package: Name-String, rating: int } |
-+-----------------+------------------------------------------------------------+
-|Pkg-Relationships| [ Pkg-Relationship, Pkg-Relationship, ... ] |
-+-----------------+------------------------------------------------------------+
-| Pkg-Relationship| { subject: Package-Name-String, |
-| | object: Package-Name-String, type: Relationship-Type, |
-| | comment: String } |
-+-----------------+------------------------------------------------------------+
-|Relationship-Type| One of: 'depends_on', 'dependency_of', |
-| | 'derives_from', 'has_derivation', |
-| | 'child_of', 'parent_of'. |
-+-----------------+------------------------------------------------------------+
-| Revision | { id: Uuid, message: String, author: String, |
-| | timestamp: Date-Time, packages: Package-List } |
-+-----------------+------------------------------------------------------------+
-| License-List | [ License, License, License, ... ] |
-+-----------------+------------------------------------------------------------+
-| License | { id: Name-String, title: String, is_okd_compliant: |
-| | Boolean, is_osi_compliant: Boolean, tags: Tag-List, |
-| | family: String, url: String, maintainer: String, |
-| | date_created: Date-Time, status: String } |
-+-----------------+------------------------------------------------------------+
-| Name-String | An alphanumeric string. |
-+-----------------+------------------------------------------------------------+
-
-To send request data, create a simple data structure, then convert it to a JSON string, then percent-encode the JSON string, then send it as the request body.
-
-Response data will be in the response body.
-
-Notes:
-
- * When you update an object, fields that you don't supply will remain as they were before.
-
- * To delete an 'extra' key-value pair, supply the key with a None value.
-
- * When you read a package then some additional information is supplied that cannot current be adjusted throught the CKAN API. This includes info on Package Relationship ('relationships'), Group membership ('groups'), ratings ('ratings_average' and 'ratings_count') and Package ID ('id'). This is purely a convenience for clients, and only forms part of the Package on GET.
-
-
-
-
--- a/doc/api/3/model/index.rst.inc Fri Jul 29 10:49:26 2011 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,14 +0,0 @@
-Model API
----------
-
-Model resources are available at published locations. They are represented with
-a variety of data formats. Each resource location supports a number of methods.
-
-The data formats of the requests and the responses are defined below.
-
-.. include:: resources.rst.inc
-
-.. include:: methods.rst.inc
-
-.. include:: formats.rst.inc
-
--- a/doc/api/3/model/methods.rst.inc Fri Jul 29 10:49:26 2011 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,49 +0,0 @@
-Model Methods
-~~~~~~~~~~~~~
-
-Here are the methods of the Model API.
-
-+-------------------------------+--------+------------------+-------------------+
-| Resource | Method | Request | Response |
-+===============================+========+==================+===================+
-| Package Register | GET | | Package-List |
-+-------------------------------+--------+------------------+-------------------+
-| Package Register | POST | Package | |
-+-------------------------------+--------+------------------+-------------------+
-| Package Entity | GET | | Package |
-+-------------------------------+--------+------------------+-------------------+
-| Package Entity | PUT | Package | |
-+-------------------------------+--------+------------------+-------------------+
-| Group Register | GET | | Group-List |
-+-------------------------------+--------+------------------+-------------------+
-| Group Register | POST | Group | |
-+-------------------------------+--------+------------------+-------------------+
-| Group Entity | GET | | Group |
-+-------------------------------+--------+------------------+-------------------+
-| Group Entity | PUT | Group | |
-+-------------------------------+--------+------------------+-------------------+
-| Tag Register | GET | | Tag-List |
-+-------------------------------+--------+------------------+-------------------+
-| Tag Entity | GET | | Package-List |
-+-------------------------------+--------+------------------+-------------------+
-| Rating Register | POST | Rating | |
-+-------------------------------+--------+------------------+-------------------+
-| Rating Entity | GET | | Rating |
-+-------------------------------+--------+------------------+-------------------+
-| Package Relationships Register| GET | | Pkg-Relationships |
-+-------------------------------+--------+------------------+-------------------+
-| Package Relationship Entity | GET | | Pkg-Relationship |
-+-------------------------------+--------+------------------+-------------------+
-| Package Relationship Entity | PUT | Pkg-Relationship | |
-+-------------------------------+--------+------------------+-------------------+
-| Revision Entity | GET | | Revision |
-+-------------------------------+--------+------------------+-------------------+
-| License List | GET | | License-List |
-+-------------------------------+--------+------------------+-------------------+
-
-* PUT operations may instead use the HTTP POST method.
-
-* POSTing data to a register resource will create a new entity, whilst PUT/POSTing data to an entity resource will update an existing entity.
-
-
-
--- a/doc/api/3/model/resources.rst.inc Fri Jul 29 10:49:26 2011 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,42 +0,0 @@
-Model Resources
-~~~~~~~~~~~~~~~
-
-Here are the resources of the Model API.
-
-+--------------------------------+-------------------------------------------------------------------+
-| Resource | Location |
-+================================+===================================================================+
-| Package Register | ``/api/rest/package`` |
-+--------------------------------+-------------------------------------------------------------------+
-| Package Entity | ``/api/rest/package/PACKAGE-REF`` |
-+--------------------------------+-------------------------------------------------------------------+
-| Group Register | ``/api/rest/group`` |
-+--------------------------------+-------------------------------------------------------------------+
-| Group Entity | ``/api/rest/group/GROUP-NAME`` |
-+--------------------------------+-------------------------------------------------------------------+
-| Tag Register | ``/api/rest/tag`` |
-+--------------------------------+-------------------------------------------------------------------+
-| Tag Entity | ``/api/rest/tag/TAG-NAME`` |
-+--------------------------------+-------------------------------------------------------------------+
-| Rating Register | ``/api/rest/rating`` |
-+--------------------------------+-------------------------------------------------------------------+
-| Rating Entity | ``/api/rest/rating/PACKAGE-REF`` |
-+--------------------------------+-------------------------------------------------------------------+
-| Package Relationships Register | ``/api/rest/package/PACKAGE-REF/relationships`` |
-+--------------------------------+-------------------------------------------------------------------+
-| Package Relationships Register | ``/api/rest/package/PACKAGE-REF/relationships/PACKAGE-REF`` |
-+--------------------------------+-------------------------------------------------------------------+
-| Package Relationship Entity | ``/api/rest/package/PACKAGE-REF/RELATIONSHIP-TYPE/PACKAGE-REF`` |
-+--------------------------------+-------------------------------------------------------------------+
-| Revision Register | ``/api/rest/revision`` |
-+--------------------------------+-------------------------------------------------------------------+
-| Revision Entity | ``/api/rest/revision/REVISION-ID`` |
-+--------------------------------+-------------------------------------------------------------------+
-| License List | ``/api/rest/licenses`` |
-+--------------------------------+-------------------------------------------------------------------+
-
-Possible values for PACKAGE-REF are the package id, or the current package name.
-
-Possible values for RELATIONSHIP-TYPE are described in the Relationship-Type data format.
-
-
--- a/doc/api/3/overview.rst.inc Fri Jul 29 10:49:26 2011 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,12 +0,0 @@
-API Overview
--------------
-
-The CKAN API is separated into three parts:
-
-* `Model API`_
-* `Search API`_
-
-The CKAN API follows the RESTful (Representational State Transfer)
-style. Published resources are separated both from the methods supported by
-the resources, and from the data formats and status codes used by the methods.
-
--- a/doc/api/3/search/formats.rst.inc Fri Jul 29 10:49:26 2011 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,127 +0,0 @@
-Search Formats
-~~~~~~~~~~~~~~~~~~~
-
-Here are the data formats for the Search API.
-
-+-------------------------+------------------------------------------------------------+
-| Name | Format |
-+=========================+============================================================+
-| Package-Search-Params | { Param-Key: Param-Value, Param-Key: Param-Value, ... } |
-| Resource-Search-Params | See below for full details of search parameters across the |
-| Revision-Search-Params | various domain objects. |
-+-------------------------+------------------------------------------------------------+
-| Package-Search-Response | { count: Count-int, results: [Package, Package, ... ] } |
-+-------------------------+------------------------------------------------------------+
-| Resource-Search-Response| { count: Count-int, results: [Resource, Resource, ... ] } |
-+-------------------------+------------------------------------------------------------+
-| Revision-List | [ Revision-Id, Revision-Id, Revision-Id, ... ] |
-| | NB: Ordered with youngest revision first |
-+-------------------------+------------------------------------------------------------+
-| Tag-Count-List | [ [Name-String, Integer], [Name-String, Integer], ... ] |
-+-------------------------+------------------------------------------------------------+
-
-The ``Package`` and ``Revision`` data formats are as defined in `Model Formats`_.
-
-
-Package Search Parameters
-""""""""""""""""""""""""""
-
-+-----------------------+---------------+----------------------------------+----------------------------------+
-| Param-Key | Param-Value | Example | Notes |
-+=======================+===============+==================================+==================================+
-| q | Search-String || q=geodata | Criteria to search the package |
-| | || q=government+sweden | fields for. URL-encoded search |
-| | || q=%22drug%20abuse%22 | text. (You can also concatenate |
-| | | | words with a '+' symbol in a |
-| | | | URL.) Search results must contain|
-| | | | all the specified words. |
-+-----------------------+---------------+----------------------------------+----------------------------------+
-| qjson | JSON encoded | ['q':'geodata'] | All search parameters can be |
-| | options | | json-encoded and supplied to this|
-| | | | parameter as a more flexible |
-| | | | alternative in GET requests. |
-+-----------------------+---------------+----------------------------------+----------------------------------+
-|title, | Search-String | title=uk&tags=health+census | Search a particular a field. Note|
-|tags, notes, groups, | | | that the latter fields mentioned |
-|author, maintainer, | | | here are in the 'extra' fields. |
-|update_frequency, | | | |
-|geographic_granularity,| | | |
-|geographic_coverage, | | | |
-|temporal_granularity, | | | |
-|temporal_coverage, | | | |
-|national_statistic, | | | |
-|categories, | | | |
-|precision, | | | |
-|department, agency, | | | |
-|external_reference | | | |
-+-----------------------+---------------+----------------------------------+----------------------------------+
-| order_by | field-name | order_by=name | Specify either rank or the field |
-| | (default=rank)| | to sort the results by |
-+-----------------------+---------------+----------------------------------+----------------------------------+
-| offset, limit | result-int | offset=40&limit=20 | Pagination options. Offset is the|
-| | (defaults: | | number of the first result and |
-| | offset=0, | | limit is the number of results to|
-| | limit=20) | | return. |
-+-----------------------+---------------+----------------------------------+----------------------------------+
-| all_fields | 0 (default) | all_fields=1 | Each matching search result is |
-| | or 1 | | given as either a package name |
-| | | | (0) or the full package record |
-| | | | (1). |
-+-----------------------+---------------+----------------------------------+----------------------------------+
-| filter_by_openness | 0 (default) | filter_by_openness=1 | Filters results by ones which are|
-| | or 1 | | open. |
-+-----------------------+---------------+----------------------------------+----------------------------------+
-|filter_by_downloadbable| 0 (default) | filter_by_downloadable=1 | Filters results by ones which |
-| | or 1 | | have at least one resource URL. |
-+-----------------------+---------------+----------------------------------+----------------------------------+
-
-
-Resource Search Parameters
-""""""""""""""""""""""""""
-
-+-----------------------+---------------+-----------------------------------------+----------------------------------+
-| Param-Key | Param-Value | Example | Notes |
-+=======================+===============+=========================================+==================================+
-| url, format, | Search-String || url=statistics.org | Criteria to search the package |
-| description | || format=xls | fields for. URL-encoded search |
-| | || description=Research+Institute | text. This search string must be |
-| | | | found somewhere within the field |
-| | | | to match. |
-| | | | Case insensitive. |
-+-----------------------+---------------+-----------------------------------------+----------------------------------+
-| qjson | JSON encoded | ['url':'www.statistics.org'] | All search parameters can be |
-| | options | | json-encoded and supplied to this|
-| | | | parameter as a more flexible |
-| | | | alternative in GET requests. |
-+-----------------------+---------------+-----------------------------------------+----------------------------------+
-| hash | Search-String |hash=b0d7c260-35d4-42ab-9e3d-c1f4db9bc2f0| Searches for an match of the |
-| | | | hash field. An exact match or |
-| | | | match up to the length of the |
-| | | | hash given. |
-+-----------------------+---------------+-----------------------------------------+----------------------------------+
-| all_fields | 0 (default) | all_fields=1 | Each matching search result is |
-| | or 1 | | given as either an ID (0) or the |
-| | | | full resource record |
-+-----------------------+---------------+-----------------------------------------+----------------------------------+
-| offset, limit | result-int | offset=40&limit=20 | Pagination options. Offset is the|
-| | (defaults: | | number of the first result and |
-| | offset=0, | | limit is the number of results to|
-| | limit=20) | | return. |
-+-----------------------+---------------+-----------------------------------------+----------------------------------+
-
-
-Revision Search Parameters
-""""""""""""""""""""""""""
-
-+-----------------------+---------------+-----------------------------------------------------+----------------------------------+
-| Param-Key | Param-Value | Example | Notes |
-+=======================+===============+=====================================================+==================================+
-| since_time | Date-Time | since_time=2010-05-05T19:42:45.854533 | The time can be less precisely |
-| | | | stated (e.g 2010-05-05). |
-+-----------------------+---------------+-----------------------------------------------------+----------------------------------+
-| since_id | Uuid | since_id=6c9f32ef-1f93-4b2f-891b-fd01924ebe08 | The stated id will not be |
-| | | | included in the results. |
-+-----------------------+---------------+-----------------------------------------------------+----------------------------------+
-
-
-
--- a/doc/api/3/search/index.rst.inc Fri Jul 29 10:49:26 2011 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,9 +0,0 @@
-Search API
----------------
-
-.. include:: resources.rst.inc
-
-.. include:: methods.rst.inc
-
-.. include:: formats.rst.inc
-
--- a/doc/api/3/search/methods.rst.inc Fri Jul 29 10:49:26 2011 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,22 +0,0 @@
-Search Methods
-~~~~~~~~~~~~~~
-
-Here are the methods of the Search API.
-
-+-------------------------------+--------+------------------------+--------------------------+
-| Resource | Method | Request | Response |
-+===============================+========+========================+==========================+
-| Package Search | POST | Package-Search-Params | Package-Search-Response |
-+-------------------------------+--------+------------------------+--------------------------+
-| Resource Search | POST | Resource-Search-Params | Resource-Search-Response |
-+-------------------------------+--------+------------------------+--------------------------+
-| Revision Search | POST | Revision-Search-Params | Revision-List |
-+-------------------------------+--------+------------------------+--------------------------+
-| Tag Counts | GET | | Tag-Count-List |
-+-------------------------------+--------+------------------------+--------------------------+
-
-It is also possible to supply the search parameters in the URL of a GET request,
-for example ``/api/search/package?q=geodata&allfields=1``.
-
-
-
--- a/doc/api/3/search/resources.rst.inc Fri Jul 29 10:49:26 2011 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,19 +0,0 @@
-Search Resources
-~~~~~~~~~~~~~~~~
-
-Here are the published resources of the Search API.
-
-+---------------------------+--------------------------+
-| Resource | Location |
-+===========================+==========================+
-| Package Search | ``/api/search/package`` |
-+---------------------------+--------------------------+
-| Resource Search | ``/api/search/resource`` |
-+---------------------------+--------------------------+
-| Revision Search | ``/api/search/revision`` |
-+---------------------------+--------------------------+
-| Tag Counts | ``/api/tag_counts`` |
-+---------------------------+--------------------------+
-
-See below for more information about package and revision search parameters.
-
--- a/doc/api/3/status.rst.inc Fri Jul 29 10:49:26 2011 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,18 +0,0 @@
-Status Codes
-------------
-
-Standard HTTP status codes are used to signal method outcomes.
-
-===== =====
-Code Name
-===== =====
-200 OK
-301 Moved Permanently
-400 Bad Request
-403 Not Authorized
-404 Not Found
-409 Conflict (e.g. name already exists)
-500 Service Error
-===== =====
-
-
--- a/doc/api/bottom.rst.inc Fri Jul 29 10:49:26 2011 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,3 +0,0 @@
-.. include:: keys.rst.inc
-.. include:: status.rst.inc
-.. include:: jsonp.rst.inc
--- a/doc/api/clients.rst.inc Fri Jul 29 10:49:26 2011 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,7 +0,0 @@
-Code Modules for Client Applications
--------------------------------------
-
-There are also some code modules (Python, PHP, Drupal, Perl etc.) that provide
-convenient wrappers around much of the CKAN API. For full details of these,
-please consult http://wiki.ckan.net/API
-
--- a/doc/api/example.rst.inc Fri Jul 29 10:49:26 2011 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,43 +0,0 @@
-Example of Usage
-----------------
-
-Let's say you're using ckan.net and want a list of all the packages. If you GET
-`<http://ckan.net/api/rest/package>`_ then it will return the list of the package
-names in JSON format::
-
-["2000-us-census-rdf", "32000-naples-florida-businesses-kml", "aaoe-87", "acawiki", "adb-sdbs", "addgene", "advances-in-dental-research", ... ]
-
-There are several ways you might access this URL:
-
-* simply put this URL into your web browser and save the resulting text file
-
-* you could use a command-line program such as `curl` or `wget`
-
-* you could write a program that uses an http library
-
-* use the Python library `CKAN Client <http://pypi.python.org/pypi/ckanclient>`_
-
-* use command-line tool `Datapkg <http://packages.python.org/datapkg/>`_. It manages datasets in a similar way as getting software packages with `apt-get` or `CPAN`.
-
-You could search for packages to do with 'open street map' like this: `<http://ckan.net/api/search/package?q=open+street+map>`_ returning::
-
-{"count": 4, "results": ["uk-naptan-osm", "osm-uk", "osm", "naptan"]}
-
-You can see the full record for the `osm` package in JSON format with this: `<http://ckan.net/api/rest/package/osm>`_ which returns::
-
-{"id": "a3dd8f64-9078-4f04-845c-e3f047125028", "name": "osm", "title": "Open Street Map", "version": null, "url": "http://www.openstreetmap.org/", ... }
-
-You might add a tag by a PUT to ``http://ckan.net/api/rest/package/osm`` with this data::
-
-{"tags": ["navigation", "openstreetmap", "map", "geo", "geodata", "xml", "publicdomain", "osm", "my-new-tag"]}
-
-Here we use `curl` to create a new package (you'll need your own :doc:`API Key <api/version2>` to try this)::
-
-$ curl http://test.ckan.net/api/rest/package -d '{"name":"test", "title":"Test package"}' -H "Authorization: 474d34e4-b710-4b77-b89f-2e909c336b91"
-
-And we create an example package with some government data::
-
-$ curl http://test.ckan.net/api/rest/package -d '{"name": "abstract_of_scottish_agricultural_statistics", "title": "Abstract of Scottish Agricultural Statistics", "version": null, "url": null, "author": "Scottish Government", "author_email": null, "maintainer": null, "maintainer_email": null, "notes": "A long term series of all the main agriculture census items collected in the June census.\n\nSource agency: Scottish Government\n\nDesignation: National Statistics\n\nLanguage: English\n\nAlternative title: Abstract of Scottish Agricultural Statistics", "license_id": "ukcrown-withrights", "tags": ["farm-outputs", "environment", "agriculture", "farming", "agriculture-and-environment"], "extras": {"geographic_coverage": "010000: Scotland", "geographical_granularity": "Country", "external_reference": "ONSHUB", "temporal_granularity": "", "date_updated": "", "agency": "", "precision": "", "temporal_coverage_to": "", "temporal_coverage_from": "", "national_statistic": "yes", "import_source": "ONS-ons_data_50_days_to_2010-05-04", "department": "Scottish Government", "update_frequency": "", "date_released": "2010-03-17", "categories": "Agriculture and Environment"}, "resources": [{"url": "http://www.scotland.gov.uk/Topics/Statistics/Browse/Agriculture-Fisheries", "description": "1982-2008 | hub/id/119-33192", "format": ""}, {"url": "http://www.scotland.gov.uk/Topics/Statistics/Browse/Agriculture-Fisheries", "description": "1982-2007 | hub/id/119-34917", "format": ""}, {"url": "http://www.scotland.gov.uk/Topics/Statistics/Browse/Agriculture-Fisheries", "description": "1983-2009 | hub/id/119-44310", "format": ""}]}' -H "Authorization: d6c3349a-6ccf-45ef-88d4-a8e59a574bf2"
-
-
-
--- a/doc/api/form_resources.rst.inc Fri Jul 29 10:49:26 2011 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,9 +0,0 @@
-Form Resources
-~~~~~~~~~~~~~~
-
-Here are the resources of the Form API.
-
-.. include:: form_resources_table.rst.inc
-
-Possible values for PACKAGE-REF are the package id, or the current package name.
-
--- a/doc/api/howtouse.rst.inc Fri Jul 29 10:49:26 2011 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,15 +0,0 @@
-Using the API
--------------
-
-To send request data, create a simple data structure, then convert it to a JSON string, then percent-encode the JSON string, then send it as the request body. Response data will be in the response body.
-
-If using curl, the default Content-Type header will be ``application/x-www-form-urlencoded`` and the JSON string gets sent as a single parameter key. However Javascript libraries tend to set Content-Type to be ``application/json`` and the JSON string is the body to the POST. The latter content became acceptable from CKAN version 1.4.2.
-
-Notes:
-
- * When you update an object, fields that you don't supply will remain as they were before.
-
- * To delete an 'extra' key-value pair, supply the key with a None value.
-
- * When you read a package then some additional information is supplied that cannot current be adjusted throught the CKAN API. This includes info on Package Relationship ('relationships'), Group membership ('groups'), ratings ('ratings_average' and 'ratings_count') and Package ID ('id'). This is purely a convenience for clients, and only forms part of the Package on GET.
-
--- a/doc/api/interfaces1.rst.inc Fri Jul 29 10:49:26 2011 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,9 +0,0 @@
-Interfaces
-----------
-
-The |site| |api| |version| is separated into three parts.
-
-* `Model API`_
-* `Search API`_
-
-The resources, methods, and data formats of each are described below.
--- a/doc/api/interfaces2.rst.inc Fri Jul 29 10:49:26 2011 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,10 +0,0 @@
-Interfaces
-----------
-
-The |site| |api| |version| is separated into three parts.
-
-* `Model API`_
-* `Search API`_
-* `Util API`_
-
-The resources, methods, and data formats of each are described below.
--- a/doc/api/jsonp.rst.inc Fri Jul 29 10:49:26 2011 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,17 +0,0 @@
-JSONP formatted responses
--------------------------
-
-To cater for scripts from other sites that wish to access the API, the data can be returned in JSONP format, where the JSON data is 'padded' with a function call. The function is named in the 'callback' parameter.
-
-Example normal request::
-
- GET /api/rest/package/pollution_stats
- returns: {"name": "pollution_stats", ... }
-
-but now with the callback parameter::
-
- GET /api/rest/package/pollution_stats?callback=jsoncallback
- returns: jsoncallback({"name": "pollution_stats", ... });
-
-This parameter can apply to all GET requests in the API.
-
--- a/doc/api/keys.rst.inc Fri Jul 29 10:49:26 2011 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,35 +0,0 @@
-API Keys
---------
-
-You will need to supply an API Key for certain requests to the CKAN API:
-
-* For any action which makes a change to a resource (i.e. all POST methods on register resources, and PUT/POST methods on entity resources).
-
-* If the particular resource's authorization set-up is not open to
- visitors for the action.
-
-To obtain your API key:
-
-1. Log-in to the particular CKAN website: /user/login
-
-2. The user page has a link to the API Key: /user/apikey
-
-The key should be passed in the API request header:
-
-================= =====
-Header Example value
-================= =====
-Authorization fde34a3c-b716-4c39-8dc4-881ba115c6d4
-================= =====
-
-If requests that are required to be authorized are not sent with a
-valid Authorization header, for example the user associated with the
-key is not authorized for the operation, or the header is somehow malformed,
-then the requested operation will not be carried out and the CKAN API will
-respond with status code 403.
-
-For more information about HTTP Authorization header, please refer to section
-14.8 of `RFC 2616 <http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.8>`_.
-
-
-
--- a/doc/api/location.rst.inc Fri Jul 29 10:49:26 2011 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,13 +0,0 @@
-Locators
---------
-
-The locator for a given resource can be formed by appending
-the relative path for that resource to the API locator.
-
- ``Resource Locator = API Locator + Resource Path``
-
-The API locator for the |site| |api| |version| is:
-
- |base_location|
-
-The relative paths for each resource are listed in the sections below.
--- a/doc/api/model_formats.rst.inc Fri Jul 29 10:49:26 2011 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,31 +0,0 @@
-Model Formats
-~~~~~~~~~~~~~
-
-Here are the data formats for the Model API.
-
-.. include:: model_formats_table.rst.inc
-
-.. |format-package-ref| replace:: Package-Id
-
-.. |format-package-register| replace:: [ |format-package-ref|, |format-package-ref|, |format-package-ref|, ... ]
-
-.. |format-package-entity| replace:: { id: Uuid, name: Name-String, title: String, version: String, url: String, resources: [ Resource, Resource, ...], author: String, author_email: String, maintainer: String, maintainer_email: String, license_id: String, tags: Tag-List, notes: String, extras: { Name-String: String, ... } }
-
-.. |format-group-ref| replace:: Group-Id
-
-.. |format-group-register| replace:: [ |format-group-ref|, |format-group-ref|, |format-group-ref|, ... ]
-
-.. |format-group-entity| replace:: { name: Name-String, title: String, description: String, packages: Package-List }
-
-
-To send request data, create the JSON-format string (encode in UTF8) put it in the request body and send it using PUT or POST.
-
-Response data will be in the response body in JSON format.
-
-Notes:
-
- * When you update an object, fields that you don't supply will remain as they were before.
-
- * To delete an 'extra' key-value pair, supply the key with JSON value: ``null``
-
- * When you read a package then some additional information is supplied that cannot current be adjusted throught the CKAN API. This includes info on Package Relationship ('relationships'), Group membership ('groups'), ratings ('ratings_average' and 'ratings_count'), full URL of the package in CKAN ('ckan_url') and Package ID ('id'). This is purely a convenience for clients, and only forms part of the Package on GET.
--- a/doc/api/model_formats_table.rst.inc Fri Jul 29 10:49:26 2011 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,49 +0,0 @@
-+--------------------+------------------------------------------------------------+
-| Name | Format |
-+====================+============================================================+
-| Package-List | |format-package-register| |
-+--------------------+------------------------------------------------------------+
-| Package | |format-package-entity| |
-| | See note below on additional fields upon GET of a package. |
-+--------------------+------------------------------------------------------------+
-| Group-List | |format-group-register| |
-+--------------------+------------------------------------------------------------+
-| Group | |format-group-entity| |
-+--------------------+------------------------------------------------------------+
-| Tag-List | [ Name-String, Name-String, Name-String, ... ] |
-+--------------------+------------------------------------------------------------+
-| Tag | { name: Name-String } |
-+--------------------+------------------------------------------------------------+
-| Resource | { url: String, format: String, description: String, |
-| | hash: String } |
-+--------------------+------------------------------------------------------------+
-| Rating | { package: Name-String, rating: int } |
-+--------------------+------------------------------------------------------------+
-| Pkg-Relationships | [ Pkg-Relationship, Pkg-Relationship, ... ] |
-+--------------------+------------------------------------------------------------+
-| Pkg-Relationship | { subject: Package-Name-String, |
-| | object: Package-Name-String, type: Relationship-Type, |
-| | comment: String } |
-+--------------------+------------------------------------------------------------+
-| Pkg-Revisions | [ Pkg-Revision, Pkg-Revision, Pkg-Revision, ... ] |
-+--------------------+------------------------------------------------------------+
-| Pkg-Revision | { id: Uuid, message: String, author: String, |
-| | timestamp: Date-Time } |
-+--------------------+------------------------------------------------------------+
-|Relationship-Type | One of: 'depends_on', 'dependency_of', |
-| | 'derives_from', 'has_derivation', |
-| | 'child_of', 'parent_of'. |
-+--------------------+------------------------------------------------------------+
-| Revision-List | [ revision_id, revision_id, revision_id, ... ] |
-+--------------------+------------------------------------------------------------+
-| Revision | { id: Uuid, message: String, author: String, |
-| | timestamp: Date-Time, packages: Package-List } |
-+--------------------+------------------------------------------------------------+
-| License-List | [ License, License, License, ... ] |
-+--------------------+------------------------------------------------------------+
-| License | { id: Name-String, title: String, is_okd_compliant: |
-| | Boolean, is_osi_compliant: Boolean, tags: Tag-List, |
-| | family: String, url: String, maintainer: String, |
-| | date_created: Date-Time, status: String } |
-+--------------------+------------------------------------------------------------+
-
--- a/doc/api/model_methods.rst.inc Fri Jul 29 10:49:26 2011 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,7 +0,0 @@
-Model Methods
-~~~~~~~~~~~~~
-
-Here are the methods of the Model API.
-
-.. include:: model_methods_table.rst.inc
-
--- a/doc/api/model_methods_table.rst.inc Fri Jul 29 10:49:26 2011 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,48 +0,0 @@
-+-------------------------------+--------+------------------+-------------------+
-| Resource | Method | Request | Response |
-+===============================+========+==================+===================+
-| Package Register | GET | | Package-List |
-+-------------------------------+--------+------------------+-------------------+
-| Package Register | POST | Package | |
-+-------------------------------+--------+------------------+-------------------+
-| Package Entity | GET | | Package |
-+-------------------------------+--------+------------------+-------------------+
-| Package Entity | PUT | Package | |
-+-------------------------------+--------+------------------+-------------------+
-| Group Register | GET | | Group-List |
-+-------------------------------+--------+------------------+-------------------+
-| Group Register | POST | Group | |
-+-------------------------------+--------+------------------+-------------------+
-| Group Entity | GET | | Group |
-+-------------------------------+--------+------------------+-------------------+
-| Group Entity | PUT | Group | |
-+-------------------------------+--------+------------------+-------------------+
-| Tag Register | GET | | Tag-List |
-+-------------------------------+--------+------------------+-------------------+
-| Tag Entity | GET | | Package-List |
-+-------------------------------+--------+------------------+-------------------+
-| Rating Register | POST | Rating | |
-+-------------------------------+--------+------------------+-------------------+
-| Rating Entity | GET | | Rating |
-+-------------------------------+--------+------------------+-------------------+
-| Package Relationships Register| GET | | Pkg-Relationships |
-+-------------------------------+--------+------------------+-------------------+
-| Package Relationship Entity | GET | | Pkg-Relationship |
-+-------------------------------+--------+------------------+-------------------+
-| Package Relationship Entity | PUT | Pkg-Relationship | |
-+-------------------------------+--------+------------------+-------------------+
-| Package\'s Revisions Entity | GET | | Pkg-Revisions |
-+-------------------------------+--------+------------------+-------------------+
-| Revision List | GET | | Revision-List |
-+-------------------------------+--------+------------------+-------------------+
-| Revision Entity | GET | | Revision |
-+-------------------------------+--------+------------------+-------------------+
-| License List | GET | | License-List |
-+-------------------------------+--------+------------------+-------------------+
-
-* POSTing data to a register resource will create a new entity.
-
-* PUT/POSTing data to an entity resource will update an existing entity.
-
-* PUT operations may instead use the HTTP POST method.
-
--- a/doc/api/model_preamble.rst.inc Fri Jul 29 10:49:26 2011 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,7 +0,0 @@
-Model resources are available at published locations. They are represented with
-a variety of data formats. Each resource location supports a number of methods.
-
-The data formats of the requests and the responses are defined below.
-
-
-
--- a/doc/api/model_resources.rst.inc Fri Jul 29 10:49:26 2011 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,7 +0,0 @@
-Model Resources
-~~~~~~~~~~~~~~~
-
-Here are the resources of the Model API.
-
-.. include:: model_resources_table.rst.inc
-
--- a/doc/api/model_resources_table.rst.inc Fri Jul 29 10:49:26 2011 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,40 +0,0 @@
-
-+--------------------------------+-------------------------------------------------------------------+
-| Model Resource | Location |
-+================================+===================================================================+
-| Package Register | ``/rest/package`` |
-+--------------------------------+-------------------------------------------------------------------+
-| Package Entity | ``/rest/package/PACKAGE-REF`` |
-+--------------------------------+-------------------------------------------------------------------+
-| Group Register | ``/rest/group`` |
-+--------------------------------+-------------------------------------------------------------------+
-| Group Entity | ``/rest/group/GROUP-REF`` |
-+--------------------------------+-------------------------------------------------------------------+
-| Tag Register | ``/rest/tag`` |
-+--------------------------------+-------------------------------------------------------------------+
-| Tag Entity | ``/rest/tag/TAG-NAME`` |
-+--------------------------------+-------------------------------------------------------------------+
-| Rating Register | ``/rest/rating`` |
-+--------------------------------+-------------------------------------------------------------------+
-| Package Relationships Register | ``/rest/package/PACKAGE-REF/relationships`` |
-+--------------------------------+-------------------------------------------------------------------+
-| Package Relationships Register | ``/rest/package/PACKAGE-REF/RELATIONSHIP-TYPE`` |
-+--------------------------------+-------------------------------------------------------------------+
-| Package Relationships Register | ``/rest/package/PACKAGE-REF/relationships/PACKAGE-REF`` |
-+--------------------------------+-------------------------------------------------------------------+
-| Package Relationship Entity | ``/rest/package/PACKAGE-REF/RELATIONSHIP-TYPE/PACKAGE-REF`` |
-+--------------------------------+-------------------------------------------------------------------+
-| Package\'s Revisions Entity | ``/rest/package/PACKAGE-REF/revisions`` |
-+--------------------------------+-------------------------------------------------------------------+
-| Revision Register | ``/rest/revision`` |
-+--------------------------------+-------------------------------------------------------------------+
-| Revision Entity | ``/rest/revision/REVISION-ID`` |
-+--------------------------------+-------------------------------------------------------------------+
-| License List | ``/rest/licenses`` |
-+--------------------------------+-------------------------------------------------------------------+
-
-Possible values for PACKAGE-REF are the package id, or the current package name.
-
-Possible values for RELATIONSHIP-TYPE are described in the Relationship-Type data format.
-
-
--- a/doc/api/overview.rst.inc Fri Jul 29 10:49:26 2011 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,16 +0,0 @@
-Overview
---------
-
-The |site| data catalog is not only available in a web browser, but also
-via its Application Programming Interface (API).
-
-The |api| can be used |usage| the catalog. This document describes the
-resource locations, data formats, and status codes which comprise the |site|
-|api|, so that anyone can create software applications that use the |api|
-service.
-
-The |site| |api| follows the RESTful (Representational State
-Transfer) style. Resource locations are separated both from the methods
-supported by the resources, and from the data formats and status codes
-used by the methods.
-
--- a/doc/api/purpose.rst.inc Fri Jul 29 10:49:26 2011 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,1 +0,0 @@
-This document describes |version| of the |main_doc|.
\ No newline at end of file
--- a/doc/api/search/index.rst.inc Fri Jul 29 10:49:26 2011 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,9 +0,0 @@
-Search API
----------------
-
-.. include:: resources.rst.inc
-
-.. include:: methods.rst.inc
-
-.. include:: formats.rst.inc
-
--- a/doc/api/search/package_params_table.rst.inc Fri Jul 29 10:49:26 2011 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,42 +0,0 @@
-+-----------------------+---------------+----------------------------------+----------------------------------+
-| Param-Key | Param-Value | Examples | Notes |
-+=======================+===============+==================================+==================================+
-| q | Search-String || q=geodata | Criteria to search the package |
-| | || q=government+sweden | fields for. URL-encoded search |
-| | || q=%22drug%20abuse%22 | text. (You can also concatenate |
-| | | | words with a '+' symbol in a |
-| | | | URL.) Search results must contain|
-| | | | all the specified words. |
-+-----------------------+---------------+----------------------------------+----------------------------------+
-| qjson | JSON encoded | ['q':'geodata'] | All search parameters can be |
-| | options | | json-encoded and supplied to this|
-| | | | parameter as a more flexible |
-| | | | alternative in GET requests. |
-+-----------------------+---------------+----------------------------------+----------------------------------+
-|title, | Search-String || title=uk&tags=health+census | Search in a particular a field. |
-|tags, notes, groups, | || department=environment | |
-|author, maintainer, | | | |
-|update_frequency, or | | | |
-|any 'extra' field name | | | |
-|e.g. department | | | |
-+-----------------------+---------------+----------------------------------+----------------------------------+
-| order_by | field-name | order_by=name | Specify either rank or the field |
-| | (default=rank)| | to sort the results by |
-+-----------------------+---------------+----------------------------------+----------------------------------+
-| offset, limit | result-int | offset=40&limit=20 | Pagination options. Offset is the|
-| | (defaults: | | number of the first result and |
-| | offset=0, | | limit is the number of results to|
-| | limit=20) | | return. |
-+-----------------------+---------------+----------------------------------+----------------------------------+
-| all_fields | 0 (default) | all_fields=1 | Each matching search result is |
-| | or 1 | | given as either a package name |
-| | | | (0) or the full package record |
-| | | | (1). |
-+-----------------------+---------------+----------------------------------+----------------------------------+
-| filter_by_openness | 0 (default) | filter_by_openness=1 | Filters results by ones which are|
-| | or 1 | | open. |
-+-----------------------+---------------+----------------------------------+----------------------------------+
-|filter_by_downloadbable| 0 (default) | filter_by_downloadable=1 | Filters results by ones which |
-| | or 1 | | have at least one resource URL. |
-+-----------------------+---------------+----------------------------------+----------------------------------+
-
--- a/doc/api/search/resource_params_table.rst.inc Fri Jul 29 10:49:26 2011 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,30 +0,0 @@
-+-----------------------+---------------+-----------------------------------------+----------------------------------+
-| Param-Key | Param-Value | Example | Notes |
-+=======================+===============+=========================================+==================================+
-| url, format, | Search-String || url=statistics.org | Criteria to search the package |
-| description | || format=xls | fields for. URL-encoded search |
-| | || description=Research+Institute | text. This search string must be |
-| | | | found somewhere within the field |
-| | | | to match. |
-| | | | Case insensitive. |
-+-----------------------+---------------+-----------------------------------------+----------------------------------+
-| qjson | JSON encoded | ['url':'www.statistics.org'] | All search parameters can be |
-| | options | | json-encoded and supplied to this|
-| | | | parameter as a more flexible |
-| | | | alternative in GET requests. |
-+-----------------------+---------------+-----------------------------------------+----------------------------------+
-| hash | Search-String |hash=b0d7c260-35d4-42ab-9e3d-c1f4db9bc2f0| Searches for an match of the |
-| | | | hash field. An exact match or |
-| | | | match up to the length of the |
-| | | | hash given. |
-+-----------------------+---------------+-----------------------------------------+----------------------------------+
-| all_fields | 0 (default) | all_fields=1 | Each matching search result is |
-| | or 1 | | given as either an ID (0) or the |
-| | | | full resource record |
-+-----------------------+---------------+-----------------------------------------+----------------------------------+
-| offset, limit | result-int | offset=40&limit=20 | Pagination options. Offset is the|
-| | (defaults: | | number of the first result and |
-| | offset=0, | | limit is the number of results to|
-| | limit=20) | | return. |
-+-----------------------+---------------+-----------------------------------------+----------------------------------+
-
--- a/doc/api/search/revision_params_table.rst.inc Fri Jul 29 10:49:26 2011 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,10 +0,0 @@
-+-----------------------+---------------+-----------------------------------------------------+----------------------------------+
-| Param-Key | Param-Value | Example | Notes |
-+=======================+===============+=====================================================+==================================+
-| since_time | Date-Time | since_time=2010-05-05T19:42:45.854533 | The time can be less precisely |
-| | | | stated (e.g 2010-05-05). |
-+-----------------------+---------------+-----------------------------------------------------+----------------------------------+
-| since_id | Uuid | since_id=6c9f32ef-1f93-4b2f-891b-fd01924ebe08 | The stated id will not be |
-| | | | included in the results. |
-+-----------------------+---------------+-----------------------------------------------------+----------------------------------+
-
--- a/doc/api/search_formats.rst.inc Fri Jul 29 10:49:26 2011 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,21 +0,0 @@
-Search Formats
-~~~~~~~~~~~~~~
-
-Here are the data formats for the Search API.
-
-.. include:: search_formats_table.rst.inc
-
-The ``Package`` and ``Revision`` data formats are as defined in `Model Formats`_.
-
-**Package Parameters**
-
-.. include:: search/package_params_table.rst.inc
-
-**Resource Parameters**
-
-.. include:: search/resource_params_table.rst.inc
-
-**Revision Parameters**
-
-.. include:: search/revision_params_table.rst.inc
-
--- a/doc/api/search_formats_table.rst.inc Fri Jul 29 10:49:26 2011 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,17 +0,0 @@
-+-------------------------+------------------------------------------------------------+
-| Name | Format |
-+=========================+============================================================+
-| Package-Search-Params | { Param-Key: Param-Value, Param-Key: Param-Value, ... } |
-| Resource-Search-Params | See below for full details of search parameters across the |
-| Revision-Search-Params | various domain objects. |
-+-------------------------+------------------------------------------------------------+
-| Package-Search-Response | { count: Count-int, results: [Package, Package, ... ] } |
-+-------------------------+------------------------------------------------------------+
-| Resource-Search-Response| { count: Count-int, results: [Resource, Resource, ... ] } |
-+-------------------------+------------------------------------------------------------+
-| Revision-List | [ Revision-Id, Revision-Id, Revision-Id, ... ] |
-| | NB: Ordered with youngest revision first |
-+-------------------------+------------------------------------------------------------+
-| Tag-Count-List | [ [Name-String, Integer], [Name-String, Integer], ... ] |
-+-------------------------+------------------------------------------------------------+
-
--- a/doc/api/search_methods.rst.inc Fri Jul 29 10:49:26 2011 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,12 +0,0 @@
-Search Methods
-~~~~~~~~~~~~~~
-
-Here are the methods of the Search API.
-
-.. include:: search_methods_table.rst.inc
-
-It is also possible to supply the search parameters in the URL of a GET request,
-for example ``/api/search/package?q=geodata&allfields=1``.
-
-
-
--- a/doc/api/search_methods_table.rst.inc Fri Jul 29 10:49:26 2011 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,12 +0,0 @@
-+-------------------------------+--------+------------------------+--------------------------+
-| Resource | Method | Request | Response |
-+===============================+========+========================+==========================+
-| Package Search | POST | Package-Search-Params | Package-Search-Response |
-+-------------------------------+--------+------------------------+--------------------------+
-| Resource Search | POST | Resource-Search-Params | Resource-Search-Response |
-+-------------------------------+--------+------------------------+--------------------------+
-| Revision Search | POST | Revision-Search-Params | Revision-List |
-+-------------------------------+--------+------------------------+--------------------------+
-| Tag Counts | GET | | Tag-Count-List |
-+-------------------------------+--------+------------------------+--------------------------+
-
--- a/doc/api/search_preamble.rst.inc Fri Jul 29 10:49:26 2011 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,4 +0,0 @@
-Search resources are available at published locations. They are represented with
-a variety of data formats. Each resource location supports a number of methods.
-
-The data formats of the requests and the responses are defined below.
--- a/doc/api/search_resources.rst.inc Fri Jul 29 10:49:26 2011 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,9 +0,0 @@
-Search Resources
-~~~~~~~~~~~~~~~~
-
-Here are the published resources of the Search API.
-
-.. include:: search_resources_table.rst.inc
-
-See below for more information about package and revision search parameters.
-
--- a/doc/api/search_resources_table.rst.inc Fri Jul 29 10:49:26 2011 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,13 +0,0 @@
-+---------------------------+--------------------------+
-| Search Resource | Location |
-+===========================+==========================+
-| Package Search | ``/search/package`` |
-+---------------------------+--------------------------+
-| Resource Search | ``/search/resource`` |
-+---------------------------+--------------------------+
-| Revision Search | ``/search/revision`` |
-+---------------------------+--------------------------+
-| Tag Counts | ``/tag_counts`` |
-+---------------------------+--------------------------+
-
-
--- a/doc/api/status.rst.inc Fri Jul 29 10:49:26 2011 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,18 +0,0 @@
-Status Codes
-------------
-
-Standard HTTP status codes are used to signal method outcomes.
-
-===== =====
-Code Name
-===== =====
-200 OK
-301 Moved Permanently
-400 Bad Request
-403 Not Authorized
-404 Not Found
-409 Conflict (e.g. name already exists)
-500 Service Error
-===== =====
-
-
--- a/doc/api/title.rst.inc Fri Jul 29 10:49:26 2011 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,3 +0,0 @@
-|site| |api| |version|
-======================
-
--- a/doc/api/version1.rst Fri Jul 29 10:49:26 2011 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,39 +0,0 @@
-.. toctree::
- :hidden:
-
-.. include:: title.rst.inc
-.. include:: purpose.rst.inc
-.. include:: warning.rst.inc
-.. include:: overview.rst.inc
-.. include:: interfaces1.rst.inc
-.. include:: location.rst.inc
-
-Model API
----------
-
-.. include:: model_preamble.rst.inc
-.. include:: model_resources.rst.inc
-.. include:: model_methods.rst.inc
-.. include:: model_formats.rst.inc
-
-Search API
-----------
-
-.. include:: search_preamble.rst.inc
-.. include:: search_resources.rst.inc
-.. include:: search_methods.rst.inc
-.. include:: search_formats.rst.inc
-
-.. include:: bottom.rst.inc
-
-.. |site| replace:: CKAN
-.. |api| replace:: API
-.. |version| replace:: Version 1
-.. |base_location| replace:: ``http://ckan.net/api/1``
-.. |main_doc| replace:: :doc:`../api`
-.. |usage| replace:: to view and change
-
-.. |format-package-ref| replace:: Package-Name
-.. |format-group-ref| replace:: Group-Name
-
-
--- a/doc/api/version2.rst Fri Jul 29 10:49:26 2011 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,107 +0,0 @@
-.. toctree::
- :hidden:
-
-.. include:: title.rst.inc
-.. include:: purpose.rst.inc
-.. include:: overview.rst.inc
-.. include:: interfaces2.rst.inc
-.. include:: location.rst.inc
-
-Model API
----------
-
-.. include:: model_preamble.rst.inc
-.. include:: model_resources.rst.inc
-.. include:: model_methods.rst.inc
-.. include:: model_formats.rst.inc
-
-Search API
-----------
-
-.. include:: search_preamble.rst.inc
-.. include:: search_resources.rst.inc
-.. include:: search_methods.rst.inc
-.. include:: search_formats.rst.inc
-
-.. include:: bottom.rst.inc
-
-Util API
---------
-
-Some of CKAN's client-side Javascript code makes calls to the CKAN API. For
-example, to generate a suggestion for a package name when adding a new package
-the following API call is made:
-
-::
-
- /api/2/util/package/create_slug?title=Package+1+Title+Typed+So+Far
-
-The return value is a JSON data structure:
-
-::
-
- {"valid": true, "name": "package_1_title_typed_so_far"}
-
-These are the keys returned:
-
-``valid``
-
- Can be ``True`` or ``False``. It is ``true`` when the title entered can be
- successfully turned into a package name and when that package name is not
- already being used. It is ``false`` otherwise.
-
-``name``
-
- The suggested name for the package, based on the title
-
-You can also add ``callback=callback`` to have the response returned as JSONP. eg:
-
-This URL:
-
-::
-
- /api/2/util/package/create_slug?title=Package+1+Title+Typed+So+Far&callback=callback
-
-Returns:
-
-::
-
- callback({"valid": true, "name": "package_1_title_typed_so_far"});
-
-In some CKAN deployments you may have the API deployed at a different domain
-from the main CKAN code. In these circumstances you'll need to add a new option
-to the config file to tell the new package form where it should make its API
-requests to:
-
-::
-
- ckan.api_url = http://api.example.com/
-
-
-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"}]}}
-
-
-
-.. |site| replace:: CKAN
-.. |api| replace:: API
-.. |version| replace:: Version 2
-.. |warning| replace:: This is the latest version of the API.
-.. |base_location| replace:: ``http://ckan.net/api/2``
-.. |main_doc| replace:: :doc:`../api`
-.. |usage| replace:: to view and change
-
-.. |format-package-ref| replace:: Package-Id
-.. |format-group-ref| replace:: Group-Id
-
--- a/doc/api/versions.rst.inc Fri Jul 29 10:49:26 2011 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,30 +0,0 @@
-.. |oldest_version| replace:: 1
-
-Versions
---------
-
-The |site| |api| is versioned, so that backwards incompatible changes can be
-introduced without removing existing support. A particular version of the API
-can be used by including its version number after the API location and before
-the resource location.
-
-If the API version is not included in the request, then the API will use the
-oldest supported version of the API to handle that request. The oldest supported
-version is currently |oldest_version|.
-
-
-Version 1
-~~~~~~~~~
-
-The |version_1_doc| is the original API. At first, package and group names were invariant, and were used in persistent references.
-
-Version 2
-~~~~~~~~~
-
-The |version_2_doc| is the latest API. Since edting the names of packages and groups is now possible, packages and groups are identified by their UUID in entity representations.
-
-.. Version 3
- ~~~~~~~~~
-
- The |version_3_doc| is the next CKAN API, and is currently unstable. Various resource locations are being changed to consolidate the interface design and help simplify the documentation and client implementations.
-
--- a/doc/api/warning.rst.inc Fri Jul 29 10:49:26 2011 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,1 +0,0 @@
-.. warning:: This version is now deprecated in favour of :doc:`version2`.
\ No newline at end of file
Repository URL: https://bitbucket.org/okfn/ckan/
--
This is a commit notification from bitbucket.org. You are receiving
this because you have the service enabled, addressing the recipient of
this email.
More information about the ckan-changes
mailing list