Hi. Is there an API documentation at OpenRefine user manual | OpenRefine or somewhere else outside the codebase? I'm not able to find one.
Hi. Is there an API documentation at OpenRefine user manual | OpenRefine or somewhere else outside the codebase? I'm not able to find one.
The internal REST API isn't supported for external use (and thus isn't documented), although this has been a requested feature.
The Java API for extension writers is basically all of the public classes/methods, which isn't very disciplined of us and gets us in trouble with breaking things because of the large surface area, although the more common extension points like imports, exporters, functions, and commands have pretty well defined patterns associated with them.
What type of API are you looking for access to?
Tom
The Java API as a REST API, from what you described. I'm looking to automate, at least one, workflow(s) with the help of tools like n8n. I have streamlined all of the steps and need very minimal manual intervention somewhere in the middle, depending on a facet.
Thus, I need the API to interact to - create a project [from database in this case], issue operation(s), check progress of the execution(s), get facets themselves (not their results), get faceted reconciliation data (not the facets themselves as opposed to the previous one), operations export, login/logout the wikibase, upload to wikibase, delete the project.
At the moment, I just take the export, apply the operations in bulk until the one where manual intervention might be necessary as I need to look at a facet, continue to the end and upload.
Referring to my earlier comment at "Scheduling breaking changes we have on our radar", I think adopting OpenAPI specification to build a REST API would be beneficial in achieving such a public API.
Using Swagger/OpenAPI to document the REST API is a good suggestion since it's pretty much the de facto standard these days. It's not undocumented due to a lack of tooling though. It's undocumented because we haven't committed to supporting it for external use with all the API stability guarantees, etc that that implies.
Concerning the earlier reference to "The Java API as a REST API," I consider the Java APIs to be separate from the REST APIs. The REST APIs can be accessed by any language which knows how to speak HTTP. The Java APIs require Java (or at least a JVM language). There is a small intersection in that Java code that implements the Command interface and gets registered as a command will show up in the REST API.
If you're looking for a way to contribute, tests which cover your "apply operations in bulk" scenario would be awesome. That has basically zero test coverage currently.
Tom
1 Like
In the case of OpenRefine, I think we can have a "loose" stability clause in our documenting with OpenAPI because OpenRefine and any tooling against it would likely slowly evolve. I wouldn't expect wild drastic changes even over the next 10 years. And I think most folks that use OpenRefine's API understand that considering we already document about this in 3 places (forum, code, documentation).
So I'm all for having someone begin documenting with OpenAPI (I'm not internally versed enough to do it) and noting within it that there is no 100% backward guarantees but that we'll "try to do our best, but sometimes forward progress has to happen in places".
2 Likes