| | 1 | == As a == |
| | 2 | |
| | 3 | CKAN client such as !ScraperWiki |
| | 4 | |
| | 5 | == I want to == |
| | 6 | |
| | 7 | search for Package Resources, either by URL or other field, or just get them all. I want to be able to get all the fields. |
| | 8 | |
| | 9 | == Proposed implementation == |
| | 10 | |
| | 11 | Add resource search API at: |
| | 12 | |
| | 13 | /api/search/resource |
| | 14 | |
| | 15 | AND resource added to model API at: |
| | 16 | |
| | 17 | api/rest/resource |
| | 18 | |
| | 19 | Functional differences from the !ScraperWiki suggested patch: |
| | 20 | |
| | 21 | * URL is not normalised |
| | 22 | |
| | 23 | * URLs are not grouped |
| | 24 | |
| | 25 | * All fields of the resource object are returned, not just the URL |
| | 26 | |
| | 27 | * Package is identified by its ID, not name or full URL. (This is for consistency in the API - you can simple prepend 'http://ckan.net/package/' to the package ID) |
| | 28 | |
| | 29 | This is to make our API more general, simple and consistent. It means that the !ScraperWiki client has to do a bit more processing to get exactly what it needs. Is this ok? |
| | 30 | |
| | 31 | === Examples === |
| | 32 | |
| | 33 | POST {{{ {"url": "scraperwiki.com", "all_fields": 1 }}}, to: /api/2/search/resource |
| | 34 | |
| | 35 | returns |
| | 36 | {{{ |
| | 37 | [{"URL": "http://scraperwiki.com/lincolnshire-councillors", "format": "CSV", "Description": "Scrape of www.lincs.gov/councillors.pdf by ScraperWiki.", "hash": "", "package_id": "b8a325c8-af2a-43f3-8245-9db7d73dfbfe"}] |
| | 38 | }}} |
| | 39 | |
| | 40 | Note use of package_id instead of package_name is something we're moving towards in the API, since names can change. When we've done ticket:341 then ckan.net/package/lincs-councillors will be a synonym of ckan.net/package/b8a325c8-af2a-43f3-8245-9db7d73dfbfe |
| | 41 | |
| | 42 | === Search Parameters === |
| | 43 | {{{ |
| | 44 | Key: q |
| | 45 | Description: Search all resource fields for the value |
| | 46 | |
| | 47 | Key: url / description / format / |
| | 48 | Description: Search particular field for the value |
| | 49 | |
| | 50 | Key: all_fields |
| | 51 | Value: 0 or 1 (0 is default) |
| | 52 | Description: If 1 (true), the full record of the package resource (and it's package reference) are returned, rather than just the PackageResource ID. |
| | 53 | |
| | 54 | May also choose to introduce 'offset' and 'limit' to page through a large number of results. |
| | 55 | |
| | 56 | == Original request == |
| | 57 | |
