[ckan-discuss] Update Data API tutorial

Wed Apr 25 11:31:41 BST 2012

> Hi All,
> 
> I've been working on a tutorial and documentation for CKAN / DataHub Data API:
> 
> <http://docs.ckan.org/en/latest/using-data-api.html>
> 
> Any feedback, especially based on usage, would be *very* welcome.
> 
> (You can also submit corrections or additions directly by hitting
> "fork and edit" on the file here:
> <https://github.com/okfn/ckan/blob/master/doc/using-data-api.rst>)
> 
> This tutorial complements general info on the DataStore here:
> 
> <http://docs.ckan.org/en/latest/datastore.html>

If I just arrive directly at the 'Using the Data API' page (rather than
clicking through to it from the earlier 'DataStore and the Data API'
page) then it's a little confusing. I think the intro on the 'Using the
Data API' page could do with a couple more sentences:

1. What is the data API and what can you do with it? All I know is it's
an API that builds on ElasticSearch, so I was surprised when I saw
examples of adding data etc. (not just searching). 'DataStore' isn't
mentioned. Maybe cross-ref the earlier chapter about the DataStore.

2. What is ElasticSearch (and link to ElasticSearch)

I didn't know what {{endpoint}} should be until I looked back at the
slideshow on the 'DataStore and the Data API' page. Maybe add a concrete
example?