Make the API non-CKAN specific

[seanh]

The protocol between the CKAN plugin and the API client currently uses CKAN-specific URLs and parameters (resource_id etc.) Define and implement a non-CKAN specific protocol, so that plugins can be written for other web apps to let them use the link checker service.

Suggested design for the API implemented by the deadoralive CKAN plugin (which could also be implemented by plugins for other software):

/get_links_to_check returns a list of objects (JSON): [ {"id" : "...", "url": "..."}, ... ]. Optionally accepts the maximum number of links to return as a JSON param: { "n": 50 }. If no param is given returns up to 50 links at a time.

Either id or url can be omitted from each object, but not both. (It is valid to provide both at the same time.)

The id can be any string, the link checker posts it back to the site along with the link check result. In CKAN this would be a resource ID. If no id is given then the link checker will just post the url back with the result and no id.

If url is missing then the link checker will use the next endpoint to request the url for an id.

/get_url_for_id, accepts a JSON object with an id string as param: {"id": "..."} and returns the corresponding URL as a JSON object: {"url": "..."}. If /get_links_to_check above returns id strings without urls then the link checker will use this endpoint to get each url in turn before checking it. If a site always provides ids from its /get_links_to_check endpoint in the first place then it doesn't need to implement /get_url_for_id.

/save_link_check_result: accepts a JSON object: {"id": "...", "url": "...", "alive": true|false}. If an id was given by /get_links_to_check then the link checker will post it back to /save_link_check_result, if not it'll just post back the url.

/save_link_check_results: like /save_link_check_result but accepts a list of JSON objects. Optional - if this endpoint doesn't work the link checker service will fall back to /save_link_check_result.

[seanh]

How do we define exactly what the URLs for each endpoint are? In ckanext-deadoralive these are
implemented using CKAN's IActions plugin interface, so they are like /api/3/action
/get_links_to_check. But we probably wouldn't want to force that on other implementations.

Perhaps it can be configurable on a per-site basis - when you add a site to the link checker service
you define its API endpoints in the link checker service's config? (These would be optional config
settings, it could use defaults.)

I think we should just define nice URLs (e.g. /deadoralive/get_links_to_check) (just some minimal namespacing to avoid name clashes) and then the CKAN extension can add routes for these and redirect them to the /api/3/action/.. action API URLs.

[seanh]

Done (needs docs)