Crews.PlanningCenter.Api 1.1.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
  • 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:

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.