Crews.PlanningCenter.Api 1.2.0

.NET Planning Center API Library

A client library for the Planning Center API built on the JSON:API Framework.

• Installation
• Setup with Dependency Injection
  • OAuth Authentication (Recommended)
    • ASP.NET Core Setup
    • Controller Usage with OAuth
    • OAuth Configuration (appsettings.json)
  • Configuration Provider (Recommended)
  • Hardcoded Configuration
• Basic Setup (Without Dependency Injection)
• Usage Examples
  • Fluent API Example
  • Querying Example
  • Pagination Example
  • Mutation Example

Installation

Crews.PlanningCenter.Api is available on NuGet:

dotnet add package Crews.PlanningCenter.Api

Setup with Dependency Injection

How you set up dependency injection depends on how you want to configure the service.

This library uses the options pattern. Options are defined in the PlanningCenterApiOptions class.

The following are valid options for configuring the service:

OAuth Authentication (Recommended)

OAuth provides a secure way for users to authenticate with their Planning Center accounts without sharing credentials. This is ideal for web applications where users need to access their own data.

ASP.NET Core Setup

using Crews.PlanningCenter.Api.Authentication;
using Crews.PlanningCenter.Api.DependencyInjection;
using Crews.PlanningCenter.Auth.Models;

var builder = WebApplication.CreateBuilder(args);

// Configure OAuth authentication
builder.Services.AddAuthentication(options =>
{
    options.DefaultScheme = "Cookies";
    options.DefaultChallengeScheme = PlanningCenterOAuthDefaults.AuthenticationScheme;
})
.AddCookie("Cookies")
.AddPlanningCenterOAuth(options =>
{
    options.ClientId = builder.Configuration["PlanningCenter:ClientId"];
    options.ClientSecret = builder.Configuration["PlanningCenter:ClientSecret"];
    
    // Add scopes for the APIs you need access to
    options.Scope.Clear();
    options.Scope.Add(PlanningCenterOAuthScope.People);
    options.Scope.Add(PlanningCenterOAuthScope.Calendar);
    options.Scope.Add(PlanningCenterOAuthScope.CheckIns);
});

// Add Planning Center API services
builder.Services.AddPlanningCenterApi();

var app = builder.Build();
app.UseAuthentication();
app.UseAuthorization();

Controller Usage with OAuth

[Authorize]
public class PlanningCenterController : Controller
{
    private readonly PeopleClient _peopleClient;

    public PlanningCenterController(PeopleClient peopleClient)
    {
        _peopleClient = peopleClient;
    }

    public async Task<IActionResult> Profile()
    {
        // API calls automatically use the authenticated user's OAuth token
        var currentUser = await _peopleClient.LatestVersion.Me.GetAsync();
        return View(currentUser.Data);
    }
}

OAuth Configuration (appsettings.json)

{
  "PlanningCenter": {
    "ClientId": "your-oauth-client-id",
    "ClientSecret": "your-oauth-client-secret"
  }
}

Configuration Provider (Recommended)

You can automatically configure the service with the provider of your choice. Here's an example using appsettings.json:

{
	"PlanningCenterApi": {
		"ApiBaseAddress": "https://api.planningcenteronline.com",
		"PersonalAccessToken": {
			"AppID": "yourAppId",
			"Secret": "yourSecret"
		},
		"HttpClientName": "myCustomClient"
	}
}

Then, in Program.cs or Startup.cs:

using Crews.PlanningCenter.Api.DependencyInjection;

// ...

builder.Services.AddPlanningCenterApi();

Hardcoded Configuration

You can also configure the service using a lambda expression during service registration:

using Crews.PlanningCenter.Api.DependencyInjection;

// ...

builder.Services.AddPlanningCenterApi(options =>
{
	options.ApiBaseAddress = new("https://api.planningcenteronline.com");
	options.PersonalAccessToken = new()
	{
		AppID = "yourAppId",
		Secret = "yourSecret"
	};
	options.HttpClientName = "myCustomClient";
});

Basic Setup (Without Dependency Injection)

Start by creating an HttpClient instance:

using Crews.Extensions.Http;
using Crews.PlanningCenter.Api.Clients;
using Crews.PlanningCenter.Api.Models;

HttpClient client = new();
client.SafelySetBaseAddress(new("https://api.planningcenteronline.com"));

// Don't forget to add your access token!
PlanningCenterPersonalAccessToken token = new()
{
	AppID = "yourAppIdHere",
	Secret = "superSecretPasswordHere"
};
client.DefaultRequestHeaders.Authorization = token;

Use this HttpClient to create a new API client of your choice, and you're off to the races!

CalendarClient calendar = new(client);

var myEvent = await calendar.LatestVersion.Events.WithID("123").GetAsync();
Console.WriteLine($"My event is called {myEvent.Data.Name}!");

Usage Examples

Fluent API Example

You can chain API resource calls to navigate the API:

var myEvent = await calendar.LatestVersion
	.Events
	.WithID("123")
	.Owner
	.EventResourceRequests
	.WithID("456")
	.ResourceBookings
	.WithID("789")
	.EventInstance
	.Event
	.GetAsync();

Querying Example

You can easily include related resources, or sort and query collections:

var myAttachments = await calendar.LatestVersion.Attachments
	.Include(AttachmentIncludable.Event)
	.OrderBy(AttachmentOrderable.FileSize, Order.Descending)
	.Query((AttachmentQueryable.Name, "myAttachment"), (AttachmentQueryable.Description, "The best attachment."))
	.GetAllAsync();

// Reading included resources must be done manually.
var includedResources = myAttachments.JsonApiDocument.GetIncludedResources();

Pagination Example

You can specify a count and an offset for collections of resources:

var myAttachments = await calendar.LatestVersion.Attachments.GetAllAsync();

Console.WriteLine(myAttachments.Metadata.TotalCount);  // Get total count of items available on the API
Console.WriteLine(myAttachments.Metadata.Next.Offset);  // Get item offset for next page of items

// Get only first five items
myAttachments = await calendar.LatestVersion.Attachments.GetAllAsync(count: 5);

// Get ten items, offset by five items
myAttachments = await calendar.LatestVersion.Attachments.GetAllAsync(count: 10, offset: 5);

Mutation Example

You can also POST, PATCH, and DELETE resources with these options:

var myEventConnection = calendar.LatestVersion
	.Events
	.WithID("123")
	.EventConnections
	.WithID("456");

EventConnection newConnection = new()
{
	ConectedToId = "123",
	ConnectedToName = "Test"
};

var postResult = await myEventConnection.PostAsync(newConnection);   // POST
var patchResult = await myEventConnection.PatchAsync(newConnection); // PATCH
await myEventConnection.DeleteAsync();                               // DELETE

S.D.G.