pavpen/nationbuilderapi

A .NET binding to NationBuilder's Web API.

NationBuilderAPI

A .NET binding to NationBuilder's Web API.

Sample Usage

using NationBuilderAPI.V1;

NationBuilderSession nbSession = new NationBuilderSession("your-nation-slug", "your-access-token");

// Iterate over all people in our nation:
foreach (AbbreviatedPerson p in nbSession.GetPeopleResults())
{
  // Use the person data.  E.g., display the name and e-mail:
  outpTextBox.AppendText("E-mail: " + p.email + ", Name: " + p.first_name + " " + p.last_name + "\n");
}

• Install the NationBuilderAPI NuGet package in your project. (If, for some reason, you can't install the NuGet package, compile this project, and reference the <NationBuilderAPI.dll> in your project.)

• You need to obtain an access token for your NationBuilder app in order to be able to call NationBuilder's API methods (endpoints). You can obtain one by completing an OAuth login and token exchange. Once you have the access token you can use it as shown above. (You can also create a 'test token' through Nation Builder's web API.)

Receive "Person created" Webhooks in a WCF Service:

// Expose this method in your WCF service, and use its URL to receive "Person created"
// webhook requests:
[WebInvoke(Method = "POST",
    BodyStyle = WebMessageBodyStyle.Bare,
    ResponseFormat = WebMessageFormat.Json,
    UriTemplate = "WebhookReception/NationBuilder/PersonCreated")]
public void NationBuilder_PersonCreated(
    NationBuilderAPI.V1.Webhooks.V4.WebhookContent<
      NationBuilderAPI.V1.Webhooks.V4.PersonWebhookPayload>
        webhookContent)
{
    NationBuilder_WebhookRequest_CheckAccess(webhookContent);

    // !!!: Process your webhookContent here.
    // Use webhookContent.payload.person.ToPerson() to get the base
    // NationBuilderAPI.V1.Person.  If you simply cast
    // webhookContent.payload.person, you'll have to resolve types when
    // serializing.
}

/// <summary>
/// Validate a webhook's security token.
/// </summary>
/// <param name="webhookContent">The webhook input payload to validate.</param>
/// <returns><c>true</c>, meaning that access was granted, or throws a
///   <see cref="System.ServiceModel.Security.SecurityAccessDeniedException"/>
///   if access was denied.</returns>
private bool NationBuilder_WebhookRequest_CheckAccess<PayloadT>(
    NationBuilderAPI.V1.Webhooks.V4.WebhookContent<PayloadT>
      webhookContent)
{
    if (webhookContent.token != "your-webhook-authentication-token")
    {
        throw new System.ServiceModel.Security.SecurityAccessDeniedException(
            "Invalid Nation Builder webhook token!");
    }

    return true;
}

Use Custom Fields

[DataContract]
class CustomPerson : Person
{
    [DataMember]
    double height;
	
	// . . .
}

[DataContract]
class CustomDonation : Donation
{
    [DataMember]
    string in_memory_of;
	
	// . . .
}


public void UseCustomFields()
{
    using (var session = new NationBuilderSession<CustomPerson, CustomDonation>(nationSlug, nationAccessToken))
    {
        var shownPersonResponse = session.ShowPerson("123");
        CustomPerson shownPerson = shownPersonResponse.person;
        
		// . . .
    }
}

Migration from v. 1.2 and Earlier

• Since the addition of custom fields, methods returning PersonResponse now take a type parameter for the custom Person type:

// Convert:
NationBuilderAPI.V1.PersonResponse res;

// into:
NationBuilderAPI.V1.PersonResponse<NationBuilderAPI.V1.Person> res;

License

This project is distributed under GPL v.2. If you need a different license for a commercial project, send me a note.

-- Pav

nationbuilderapi's Issues

Support Nation Builder Custom Fields

As a 'NationBuilderAPI' user, I would like to be able to read custom fields from Nation Builder, and store objects with custom fields in Nation Builder.

See:

http://nationbuilder.com/when_to_use_custom_fields

This feature was requested by Paul Smith (https://github.com/PaulVSmith).

Library status?

I'm considering using the NationBuilder API, and would love to do it from C#. The library was last updated 2 years ago... I'm guessing the underlying API has changed a fair amount since then - any plans for continuing this, or is it effectively on-hold? (I completely understand if so... open source commitments can play havoc with a home life.)

Getting exceptions on deserialization of Person in ShowPerson

Thank you for the wrapper.

The result of the exceptions is the person object is not populated.

Also do custom fields get loaded?

Regards

Paul