@datopian/ckan-api-client-js
v1.3.3
Published
Among other JS clients publicly available, the objectives of this one are:
Downloads
112
Readme
CKAN API client - JavaScript
Among other JS clients publicly available, the objectives of this one are:
- To be completely flexible in terms of which CKAN actions are supported, so users specify which action should be called by its name rather than my importing and calling a method implemented specifically for the given action. This ensure that all core and custom actions are supported, including all possible parameters.
- To reduce repetition when calling CKAN actions, by reading global configurations on environemnt variables (such as the CKAN URL) and having common configurations by default (e.g. all requests by default will have the "content-type" header set to "application/json", avoiding that requests are sent without it and avoing that this has to be repeated everywhere).
- To properly handle errors, by properly detecting when an error happened and throwing an error with a useful message that can be shown to the final users.
- To expose the underlying request properties, so that anything can be customized e.g. headers
NOTE: developed mainly to be used on Next.js projects.
Usage
Install the package on the project with (or npm link
for local development):
npm i @datopian/ckan-api-client-js
Set the following environment variables on your project:
NEXT_PUBLIC_CKAN_URL=http://ckan.com # <= This should be updated
Import the client with:
import CkanRequest from "ckan-api-client-js";
Methods
CkanRequest
exports 2 main methods:
CkanRequest.get("action_name", options)
CkanRequest.post("action_name", options)
options
may have the following properties:
apiKey
- CKAN API key for authorizationheaders
- Request headers. E.g.{ "Authorization": "api_token" }
json
- JSON body for POST requests. E.g.{ "id": "123" }
formData
- formData for POST requests
Examples
package_show
const dataset = await CkanRequest.get(
"package_show?id=123",
{
apiKey: "my-token"
}
);
package_patch
const dataset = await CkanRequest.post(
"package_patch",
{
headers: {
Authorization: "apikey",
},
json: { "id": "123", "title": "My new title" },
}
);
Error handling
If an exception happens, simply catch that and show its message to the user. Example:
try {
const dataset = CkanRequest.get("package_show?id=123")
} catch (e) {
alert(e.message) // E.g. "Dataset not found"
}
Development
Currently, npm link
is being used for development purposes.
To do so, simply build (npm run build
) the project and then link it (npm link ...
) on another project to test changes.