CharityCommission 10.0.12

CharityCommission.NET

A simple .NET client wrapper for The CharityCommission API

This project was based entirely off kevbite/CompaniesHouse.NET but repurposed for the Charity Commission API.

Getting Started

CharityCommission.NET can be installed via the package manager console by executing the following commandlet:

PM> Install-Package CharityCommission

Once we have the package installed, we can then create a CharityCommissionSettings with a ApiKey which can be created via the CharityCommission API website

var settings = new CharityCommissionSettings(apiKey);

We need to now create a CharityCommissionClient - passing in the settings that we've just created.

using(var client = new CharityCommissionClient(settings))
{
    // Do some work...
}

This is the object we'll use going forward for any interaction to the CharityCommission API, but don't forget to call Dispose after you've finish (or wrap in a using block).

ASP.NET Core

If you're using ASP.NET Core you can configure the IoC container with one simple extention method call. But first you'll need to install the CharityCommission.Extensions.Microsoft.DependencyInjection NuGet package.

PM> Install-Package CharityCommission.Extensions.Microsoft.DependencyInjection

Once installed, in your Startup class in the ConfigureServices method, call the AddCharityCommissionClient method on the services object.

public void ConfigureServices(IServiceCollection services)
{
    // ...
    services.AddCharityCommissionClient("Your API Key");
}

This will then register a range of interfaces in to the IoC container that can be injected in to any of your dependancies. A list of these can be found in the ServiceCollectionExtensionsTests.

For example if we wanted to use the ICharityCommissionClient which is the main facade interface, we could inject this in to our page model.

public class MyPageModel : PageModel
{
    private readonly ICharityCommissionClient _client;

    public Index2Model(ICharityCommissionClient client)
    {
        _client = client;            
    }
}

Under the hood this is using typed clients for the HttpClient used by CharityCommission.NET and it's also possible to use this package with any dependency injection framework that implements Microsoft.Extensions.DependencyInjection.Abstractions.

Usage

Searching for a charity

To search for a charity we can then pass the charity name to the SearchCharityByNameAsync method and await on the task, this will then return all related resources.

var result = await client.SearchCharityByNameAsync("Charity Name");

foreach (var item in _result.Data)
{
    // Do something...
}

Getting a charity's details

To get a company profile, we pass a company number in to the GetCharityDetailsAsync method and await on the task.

var result = await client.GetCharityDetailsAsync("10440441");

If there was no match for that company number then null will be returned.

Contributing

This project currently only implements API endpoints used by projects I've worked on. If you want to extend it to other endpoints, please do!

1. Fork
2. Hack!
3. Pull Request

Running Unit tests

In order for the integration tests to run, you need an API Key from CharityCommission API website Setup API Key in an environment variable called "CHARITY_COMMISSION_API_KEY", and then run the tests.