[ckan-changes] [okfn/ckan] 78e0d8: [templates/data-api-help][s]: rewrite pop-up api i...
GitHub
noreply at github.com
Sat Apr 21 02:44:15 UTC 2012
Branch: refs/heads/master
Home: https://github.com/okfn/ckan
Commit: 78e0d8097bf65ed30ccd3b0b6ca340f4e06dc7ce
https://github.com/okfn/ckan/commit/78e0d8097bf65ed30ccd3b0b6ca340f4e06dc7ce
Author: Rufus Pollock <rufus.pollock at okfn.org>
Date: 2012-04-20 (Fri, 20 Apr 2012)
Changed paths:
M ckan/templates/_snippet/data-api-help.html
M doc/using-data-api.rst
Log Message:
-----------
[templates/data-api-help][s]: rewrite pop-up api in light of new detailed using api docs in main help.
diff --git a/ckan/templates/_snippet/data-api-help.html b/ckan/templates/_snippet/data-api-help.html
index 5a499c9..bab65b2 100644
--- a/ckan/templates/_snippet/data-api-help.html
+++ b/ckan/templates/_snippet/data-api-help.html
@@ -15,102 +15,51 @@
</h3>
</div>
<div class="modal-body">
- <p><strong>Access resource data via a web API with powerful query
- support</strong>. Further information in the <a
- href="http://docs.ckan.org/en/latest/storage/datastore.html" target="_blank">main
- CKAN Data API and DataStore documentation</a>.</p>
+ <p><strong>Access (and update) resource data via a web API with powerful query
+ support</strong>.</p>
+
+ <ul>
+ <li>Quickstart info below</li>
+ <li><a
+ href="http://docs.ckan.org/en/latest/using-data-api.html" target="_blank">
+ Tutorial, examples and full details in main CKAN documentation</a></li>
+ </ul>
<div class="accordion-group">
<div class="accordion-heading">
- <a class="accordion-toggle" data-toggle="collapse" href=".collapse-endpoints">Endpoints »</a>
- </div>
- <div class="collapse-endpoints in accordion-body collapse">
- <div class="accordion-inner">
- <p>The Data API builds directly on ElasticSearch, with a resource API
- endpoint being equivalent to a single index 'type' in ElasticSearch.
- This means you can directly re-use <a
- href="http://www.elasticsearch.org/guide/appendix/clients.html"
- _target="blank">ElasticSearch
- client libraries</a> when connecting to the API endpoint.</p>
- <table class="table-condensed table-striped table-bordered">
- <thead></thead>
- <tbody>
- <tr>
- <th>Query example</th>
- <td>
- <code><a href="${datastore_api}/_search?size=5&pretty=true" target="_blank">${datastore_api}/_search?size=5&pretty=true</a></code>
- </td>
- </tr>
- <tr>
- <th>Schema (Mapping)</th>
- <td>
- <code><a href="${datastore_api}/_mapping" target="_blank">${datastore_api}/_mapping?pretty=true</a></code>
- </td>
- </tr>
- <tr>
- <th>Base</th>
- <td><code>${datastore_api}</code></td>
- </tr>
- </tbody>
- </table>
- </div>
- </div>
- </div>
-
- <div class="accordion-group">
- <div class="accordion-heading">
- <a class="accordion-toggle" href=".collapse-querying" data-toggle="collapse">Querying
- »</a>
+ <a class="accordion-toggle" data-toggle="collapse" href=".collapse-endpoints">Example URLs and Endpoints»</a>
</div>
- <div class="collapse collapse-querying accordion-body in">
+ <div class="collapse-endpoints in accordion-body">
<div class="accordion-inner">
- <p><strong>Basic queries</strong> can be done using the <code>q</code>
- parameter in the query string which supports the <a
- href="http://lucene.apache.org/core/old_versioned_docs/versions/3_0_0/queryparsersyntax.html"
- target="_blank">Lucene
- query parser syntax</a> and hence filters on specific fields
- (<code>e.g. fieldname:value</code>), wildcards (e.g. <code>abc*</code>)
- and more. Full query parameters and options in the <a
- href="http://www.elasticsearch.org/guide/reference/api/search/uri-request.html"
- target="_blank">ElasticSearch
- URI request docs</a>.</p>
+ <strong>Query example (first 5 results)</strong>
+ <p>
+ <code><a href="${datastore_api}/_search?size=5&pretty=true" target="_blank">${datastore_api}/_search?size=5&pretty=true</a></code>
+ </p>
+
+ <strong>Query example (results with 'jones' in <code>title</code> field)</strong>
+ <p>
+ <code><a href="${datastore_api}/_search?q=title:jones&size=5&pretty=true"
+ target="_blank">${datastore_api}/_search?q=title:jones&size=5&pretty=true</a></code>
+ </p>
- <p><strong>More complex queries</strong>, including those that involve
- faceting and statistical operations, should use the full ElasticSearch
- query language in which the query is a JSON structure sent in the
- <code>?source=</code> parameter. See <a
- href="http://www.elasticsearch.org/guide/reference/api/search/"
- target="_blank">ElasticSearch
- query documentation</a>.</p>
+ <strong>Schema (Mapping)</strong>
+ <p>
+ <code><a href="${datastore_api}/_mapping" target="_blank">${datastore_api}/_mapping?pretty=true</a></code>
+ </p>
- <p>JSONP support is available via a simple callback query parameter:
- <code>?callback=my_callback_name</code>.</p>
+ <strong>Endpoint (for clients)</strong>
+ <p>
+ <code>${datastore_api}</code>
+ </p>
</div>
</div>
</div>
<div class="accordion-group">
<div class="accordion-heading">
- <a class="accordion-toggle" href=".collapse-curl"
- data-toggle="collapse">Example: cURL (or Browser) »</a>
- </div>
- <div class="accordion-body collapse-curl collapse in">
- <div class="accordion-inner">
- <p>The following examples utilize the <a href="http://curl.haxx.se/">cURL</a>
- command line utility. If you prefer, you you can just open the relevant urls in
- your browser.</p>
-
- <pre>
-// added pretty=true to get the json results pretty printed
-curl ${datastore_api}/_search?q=title:jones&size=5&pretty=true</pre>
- </div>
- </div>
- </div>
- <div class="accordion-group">
- <div class="accordion-heading">
<a class="accordion-toggle" href=".collapse-javascript" data-toggle="collapse">Example: Javascript</a>
</div>
- <div class="accordion-body collapse-javascript collapse in">
+ <div class="accordion-body collapse-javascript in">
<div class="accordion-inner">
<p>A simple ajax (JSONP) request to the data API using jQuery.</p>
<pre>
@@ -119,7 +68,8 @@
q: 'title:jones' // query on the title field for 'jones'
};
$.ajax({
- url: ${datastore_api}/_search,
+ url: '${datastore_api}/_search',
+ data: data,
dataType: 'jsonp',
success: function(data) {
alert('Total results found: ' + data.hits.total)
@@ -128,6 +78,22 @@
</div>
</div>
</div>
+
+ <div class="accordion-group">
+ <div class="accordion-heading">
+ <a class="accordion-toggle" href=".collapse-javascript" data-toggle="collapse">Example: Python</a>
+ </div>
+ <div class="accordion-body collapse-javascript in">
+ <div class="accordion-inner">
+ <pre>
+import urllib
+url = '${datastore_api}/_search?size=5&q=title:jones'
+fileobj = urllib.urlopen(url)
+print fileobj.read()
+</pre>
+ </div>
+ </div>
+ </div>
</div>
</div>
diff --git a/doc/using-data-api.rst b/doc/using-data-api.rst
index 09c26b1..3c6a6fe 100644
--- a/doc/using-data-api.rst
+++ b/doc/using-data-api.rst
@@ -10,8 +10,7 @@ being equivalent to a single index 'type' in ElasticSearch (we tend to refer to
it as a 'table'). This means you can often directly re-use `ElasticSearch
client libraries`_ when connecting to the API endpoint.
-Furthermore, it means that almost all of what is presented below is generally
-applicable to ElasticSearch.
+Furthermore, it means that what is presented below is essentially a tutorial in the ElasticSearch API.
.. _ElasticSearch client libraries: http://www.elasticsearch.org/guide/appendix/clients.html
================================================================
More information about the ckan-changes
mailing list