Openrefine: Improve API documentation

[stellasia]

The OpenRefine API (tested on version 2.7) is very cool but documentation at https://github.com/OpenRefine/OpenRefine/wiki/OpenRefine-API is not complete.

For instance, in the "Create project" section : the URL /command/core/create-project-from-upload does not return project ID but HTML code where I was not able to find project ID information. It instead redirects to /project?project=<project_id>. It took me a while to figure this out!

More generally, in all sections, it would be useful to have a description of what parameters exactly are returned (similarly to "Expression Preview" section).

[felipemouradev]

I'm going through almost the same problem, at the endpoint of creating a new project, the response comes in an html and no ID is provided as stated in the documentation.

Has anyone managed to solve it?

[ostephens]

I'm afraid no-one has tackled that documentation yet. However, the existing code libraries that interact with OpenRefine might be a good starting point for understanding how you can exploit the API. E.g:

https://github.com/PaulMakepeace/refine-client-py/
https://github.com/maxogden/refine-python
https://github.com/maxogden/refine-ruby
https://github.com/pm5/node-openrefine

Or if there is something specific you are trying to do, you could ask on the discussion group at https://groups.google.com/forum/#!forum/openrefine

[stellasia]

Well, I do not remember exactly but I finally get it to work thanks to the https://github.com/OpenRefine/refine-python as @ostephens suggests, adapted for python3 in my case.

Relevant lines are :

from urllib import parse

 response = requests.post(self.server + '/command/core/create-project-from-upload',
                         data=data,
                         files=files,
                         headers={"Accept": "application/json"}
)
if response.status_code != 200:
  # TODO: better error reporting
  return None

response_body = parse.parse_qs(parse.urlparse(response.request.url).query)

if 'project' in response_body:
  i = response_body['project'][0]
  return RefineProject(self.server, i, project_name)

[ostephens]

I've now updated the HTTP API documentation to indicate that the project ID is not directly returned, but available from the redirected URL. Also expanded / updated some other parts of the documentation. See https://github.com/OpenRefine/OpenRefine/wiki/OpenRefine-API