Preface

If you don’t know what Ckan is, then this repository is probably not the place to start. You should check out Ckan's website and Ckan's API documentation

CkanSharp and this wiki are very much a work in a progress and there is currently no stable release.

If you want any specific information about CkanSharp or want to contribute contact @fuschia or @rossjones

About this Wiki

This wiki will eventually contain detailed information on how CkanSharp works, as well as plenty of code samples for common tasks such as creating packages/resources on a remote Ckan instance. It will be updated as work progresses and properly structured into sections and pages as time permits.

About CkanSharp

CkanSharp was conceived following the identification of a need to automatically update large numbers of packages within Leeds Data Mill. There is a larger project to deal with that automated process, involving a Windows service that will be configurable to schedule updates to any remote Ckan instance. At initial design phase of this project it was decided to modularise the Ckan interaction code into a .Net library for re-use elsewhere.

CkanSharp provides an abstraction layer to version 3 of the Ckan api, allowing developers to work with a remote Ckan instance using familiar .Net objects in an object orientated approach. All of the api communication is encapsulated within CkanSharp.

The purpose (at this time) is only to provide a simple interface for common tasks with a remote Ckan instance, not to provide the full functionality of the Ckan api. If you want some functionality that is not planned to be included you can either fork this repository and issue a pull request with your changes, or raise an issue and your request will be considered.

Future Plans

Going forward the intention is to port major versions of CkanSharp to Java and Objective C to provide the same core functionality across a broad range of platforms. There is a container repository here that is used to keep track of ideas and plans for future features and development.

Using CkanSharp

Objects within Ckan are held in the namespace CkanSharp.Abstracts The CkanCredentials class contains the necessary information to identify and authenticate to the remote Ckan instance, and is required for almost all interaction with CkanSharp.

In general classes within Abstracts will all have methods for Create and Update which can be called through an instance of the class and use the populated properties of the class in question to communicate the intention to the remote Ckan instance. Each class will also have static methods for Read and List which will return a fully populated class based on the input parameters and also return lists of the relevant abstracts.

Threading - Everything CkanSharp does is done synchronously, however network communication can take some time and you should bear this in mind if implementing CkanSharp anywhere with a UI.

Exceptions - When an error occurs Ckan may or may not respond appropriately. When a response is received from Ckan (e.g. supplied credentials aren't sufficient for the operation you've tried to perform) an exception will be thrown with the Ckan error message and Help information as a string, but you should not rely on this as it will not pick up all cases (e.g. 404).

Code Samples

TODO: keep updating this bit with common tasks as code samples

Namespaces (all samples assume you have imported the following)

#!c#

using CkanSharp;
using CkanSharp.Abstracts;

Sample: Creating a CkanCredentials instance and getting a list of packages you're allowed to edit

#!c#

string host = "http://myckansite.com"; //works with or without trailing slash
string apiKey = "REALLY_LONG_APIKEY_GOES_HERE";
string username = "MyUserName";

CkanCredentials credentials = new CkanCredentials(host, apiKey, username);
User user = credentials.CurrentUser; //CkanCredentials automatically gets the current user on instantiation
user.Organizations = Organization.GetUsersList(credentials);

foreach (Organization org in user.Organizations)
{
    foreach (Package package in org.Packages)
    {
        package = Package.Read(credentials);
        //do something interesting with the Package
    }
}

Sample: Creating a Package with some attached Resources

#!c#

string host = "http://myckansite.com"; //works with or without trailing slash
string apiKey = "REALLY_LONG_APIKEY_GOES_HERE";
string username = "MyUserName";

CkanCredentials credentials = new CkanCredentials(host, apiKey, username);

Package package = new Package();
//package name must be unique within the Ckan instance, and only contain [a-z0-9-_]
//you can check for existing package names using the static method Package.List
//which returns a list of Package abstracts
package.Name = "test-package-name";
package.Title = "Test package name";
package.Author = "Me";
package.Author_Email = "me@mywebsite.com";
package.Notes = "Some test notes about this test package";

package.Resources = new List<Resource>();
for (int i = 1; i <= 10; i++)
{
    Resource resource = new Resource();
    resource.Name = "test-resource-" + i;
    resource.Url = "http://google.com";
    package.Resources.Add(resource);
    //No need to populate package_id if nested within the package like this
}

package = package.Create(credentials);

How CkanSharp works

In general CkanSharp is quite a simple library. For most situations it just takes the populated properties of a class and creates a Json string to send to the remote Ckan instance identified within the provided instance of a CkanCredentials class. Reading is simply the reverse of this process. There is an internal class of JsonRead that is inherited as a nested private class within each class in the abstracts namespace to provide a container for mapping Ckan’s Json response to. Extensive xml comments are included for methods and classes which should provide you with all the information necessary to work with any classes should you get stuck.