Crews.PlanningCenter.Api 2.0.0

.NET Planning Center API Library

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

• Installation
• Configuration
  • OAuth Options
  • API Options
• Setup
  • ASP.NET Core Application Builder
  • Standalone
• Examples
  • Fluent API Example
  • Querying Example
  • Pagination Example
  • Mutation Example
  • Custom Resource Example

Installation

Crews.PlanningCenter.Api is available on NuGet:

dotnet add package Crews.PlanningCenter.Api

Configuration

This library uses the options pattern. By default, the following configuration sections are defined:

• Authentication:PlanningCenter: mapped to the PlanningCenterOAuthOptions class. Used for defining OAuth credentials.
• PlanningCenterApi: mapped to the PlanningCenterApiOptions class. Used for defining all other options for the library.

OAuth Options

The following are valid options for OAuth authentication:

appsettings.json example:

{
  "Authentication": {
    "PlanningCenter": {
      "ClientId": "my-client-id",
      "ClientSecret": "my-client-secret"
    }
  }
}

Manual configuration example:

builder.Services.AddAuthentication(options =>
{
  options.DefaultScheme = "Cookies";
  options.DefaultChallengeScheme = PlanningCenterOAuthDefaults.AuthenticationScheme;
})
.AddCookie("Cookies")
.AddPlanningCenterOAuth(options =>
{
  // The strings here are hardcoded for example.
  // These credentials should never be stored in your code.
  options.ClientId = "my-client-id";
  options.ClientSecret = "my-secret";
});

API Options

appsettings.json example:

{
  "PlanningCenterApi": {
    "ApiBaseAddress": "http://some-address.com",
    "HttpClientName": "my-custom-client",
    "UserAgent": "Some custom user agent string",
    "PersonalAccessToken": {
      "AppId": "my-app-id",
      "Secret": "my-secret"
    }
  }
}

Manual configuration example:

builder.Services.AddPlanningCenterApi(options =>
{
  options.ApiBaseAddress = new("http://some-address.com");
  options.HttpClientName = "my-custom-client";
  options.UserAgent = "Some custom user agent string";

  // The strings here are hardcoded for example.
  // These credentials should never be stored in your code.
  options.PersonalAccessToken = new()
  {
    AppId = "my-app-id",
    Secret = "my-secret"
  };
});

Setup

This library can be used with application builders (dependency injection), or as a standalone client.

ASP.NET Core Application Builder

First, add OAuth authentication:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddAuthentication(options =>
{
  options.DefaultScheme = "Cookies";
  options.DefaultChallengeScheme = PlanningCenterOAuthDefaults.AuthenticationScheme;
})
.AddCookie("Cookies")
.AddPlanningCenterOAuth(options =>
{
  // Add scopes for the APIs you need access to
  // By default, the "People" scope is always included
  options.Scope.Clear();
  options.Scope.Add(PlanningCenterOAuthScope.People);
  options.Scope.Add(PlanningCenterOAuthScope.Calendar);
  options.Scope.Add(PlanningCenterOAuthScope.CheckIns);
});

Next, add the Planning Center API service:

builder.Services.AddPlanningCenterApi();

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

Finally, add authentication endpoints to your app. The OAuth middleware will automatically handle token management and refreshing.

app.MapGet("/login", (HttpContext context, string? returnUrl = null) =>
{
  var properties = new AuthenticationProperties
  {
    RedirectUri = returnUrl ?? "/"
  };
  return Results.Challenge(properties, [PlanningCenterOAuthDefaults.AuthenticationScheme]);
});

app.MapPost("/logout", async (HttpContext context) =>
{
  await context.SignOutAsync("Cookies");
  return Results.Redirect("/");
});

Now you can inject IPlanningCenterApiService into your controllers or services.

[Authorize]
public class MyController(IPlanningCenterApiService _planningCenterApi) : Controller
{
  public async Task<IActionResult> Profile()
  {
    // API calls automatically use the authenticated user's OAuth token, or your personal access token
    var currentUser = await _planningCenterApi.People.LatestVersion
      .GetRelated<PersonResource>("me")
      .GetAsync();

    return View(currentUser.Data);
  }
}

Standalone

Start by creating an HttpClient instance:

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

// This example uses a personal access token.
// If you want to use OAuth in a standalone client, you're on your own.
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}!");

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"
};

// POST
var postResult = await myEventConnection.PostAsync(newConnection);

// PATCH
var patchResult = await myEventConnection.PatchAsync(newConnection);

// DELETE
await myEventConnection.DeleteAsync();

Custom Resource Example

You can define your own resource types by inheriting from either PlanningCenterSingletonFetchableResource or PlanningCenterPaginatedFetchableResource.

This provides forward compatibility by allowing you to define and fetch any resources not yet implemented in this library.

Model Creation

First, create a model class:

[JsonApiName("my_custom_resource")]
public record MyCustomModel
{
  [JsonApiName("my_first_property")]
  public string? MyFirstProperty { get; init; }

  [JsonProperty("my_second_property")]
  public int? MySecondProperty { get; init; }
}

Next, you can create your resource class.

Singleton Resource

public class MyCustomResource 
  : PlanningCenterSingletonFetchableResource<MyCustomModel, MyCustomResource, PeopleDocumentContext>,
  IIncludable<MyCustomResource, MyCustomResourceIncludable>
{
  // In this example, your resoruce has child resources of type "people"
  public PeopleResourceCollection People => GetRelated<PeopleResourceCollection>("people");

  public MyCustomSingletonResource(Uri uri, HttpClient client) : base(uri, client) { }

  // In this example, your resource has certain includable resources
  public MyCustomResource Include(params MyCustomResourceIncludable[] included) => base.Include(included);
}

Paginated Resource

public class MyCustomResourceCollection 
  : PlanningCenterPaginatedFetchableResource<MyCustomModel, MyCustomResourceCollection, MyCustomResource, PeopleDocumentContext>,
  IIncludable<MyCustomResourceCollection, MyCustomResourceIncludable>,
  IOrderable<MyCustomResourceCollection, MyCustomResourceOrderable>,
  IFilterable<MyCustomResourceCollection, MyCustomResourceQueryable>
{
  public MyCustomResourceCollection(Uri uri, HttpClient client) : base(uri, client) { }

  // In this example, your resource has certain includable resources
  public MyCustomResourceCollection Include(params MyCustomResourceIncludable[] included) => base.Include(included);

  // In this example, your resource has certain orderable properties
  public MyCustomResourceCollection OrderBy(MyCustomResourceOrderable orderable, Order order = Order.Ascending) => base.OrderBy(orderable, order);

  // In this example, your resource has certain queryable properties
  public MyCustomResourceCollection Query(params (MyCustomResourceQueryable, string)[] queries) => base.Query(queries);
}

Accessing your custom resources

Simply call the GetRelated<T>() method on any singleton resource to access your custom resource:

// Singleton
var currentUser = await planningCenterApi.People.LatestVersion
  .GetRelated<MyCustomResource>("my_custom_resource");

// Paginated
var customResources = await planningCenterApi.People.LatestVersion
  .GetRelated<MyCustomResourceCollection>("my_custom_resources");

S.D.G.