@planningcenter/api-client

Planning Center API Client

Description

A javascript library that provides a client for interacting with Planning Center's Graph API as well as helper methods for transforming request and response data.

View the classic README here.

Installation

yarn add @planningcenter/api-client

API Client

General Usage

import { Client } from "@planningcenter/api-client"
const client = new Client({ root: `${window.location.origin}/~api/services/v2/`, version: "2018-11-01" })

client.get({
  url: '/plans',
  data: {
    fields: {
      Plan: ['dates', 'series', 'title'],
    },
  }
})

Client request methods will return a promise. When the promise is resolved, you'll be left with a transformed response (see below).

Get

When making a request, the client will enforce the use of sparse fieldsets which requires the fields key.

client.get({
  url: '/plans',
  data: {
    where: { title: 'Plan Title' },
    include: ['series'],
    order: 'created_at',
    fields: {
      Plan: ['dates', 'series', 'title'],
      Series: ['title', 'artwork_for_dashboard']
    },
  }
})

🚨 NOTE: When including records you also need to define the relation in fields. See the usage of 'series' above.

Pagination

The default value of perPage is 100. You can adjust this value in the data attribute:

client.get({
  url: '/plans',
  data: {
    perPage: 25,
    fields: {
      Plan: ['title'],
    },
  }
})

If you need to return all results from a collection, instead of only the first page of results, you can include the walk: true attribute inside the data attribute:

client.get({
  url: '/plans',
  data: {
    walk: true,
    fields: {
      Plan: ['title'],
    },
  }
})

This can be used in combination with perPage to make many smaller requests for a large collection of data.

Patch

client.patch({
  url: `/series/${seriesId}`,
  data: {
    fields: { Series: 'title,artwork_for_dashboard' },
    data: { type: 'Series', attributes: { name: 'New Series Name' }
  }
})

Post

client.post({
  url: '/series',
  data: {
    fields: { Series: 'title,artwork_for_dashboard' },
    data: {
      type: 'Series',
      attributes: { name: 'New Series Name' },
      relationships: {
        plan: {
          data: { type: 'Plan', id }
        }
      }
    }
  }
})

Delete

client.delete({ url: `/series/${seriesId}` })

Helper Functions

The Client class will automatically transform request and response data, but helpers for transforming data are also available to be used manually.

transformRequestData

Takes an object with camelCase request parameters and transforms to a more api friendly format.

Input

import { transformRequestData } from "@planningcenter/api-client"

transformRequestData({
  fields: { Song: ["title", "arrangements"], Arrangement: ["name"] },
  include: "arrangements",
  where: { title: "I Like Bugs" },
})

Output

{
  "fields[Song]": "title,arrangements",
  "fields[Arrangement]": "name",
  include: "arrangements",
  per_page: 100,
  "where[title]": "I Like Bugs",
}

transformResponse

Takes an JSON API spec-adhering response and transforms it to a more appropriate format for JavaScript.

Input

import { transformResponse } from "@planningcenter/api-client"

transformResponse({
  "data": {
    "type": "Person",
    "id": "123",
    "attributes": {
      "first_name": "Marvin",
      "last_name": "Gaye"
    },
    "relationships": {
      "top_song": {
        "data": {
          "type": "Song",
          "id": "456"
        }
      },
      "instruments": {
        "data": [{
          "type": "Instrument",
          "id": "789"
        }]
      }
    },
    "links": { ... }
  },
  "included": [
    {
      "type": "Instrument",
      "id": "789",
      "attributes": {
        "name": "Piano"
      }
    }
  ],
  "meta": {
    "parent": {
      "id": "1",
      "type": "Organization"
    }
  }
})

Output

{
  data: {
    // string IDs are parsed into integers
    id: 123,
    type: "Person",

    // all keys are camel-cased
    firstName: "Marvin",
    lastName: "Gaye",

    // belongs to relationships are given a singular foreign key property
    topSongId: 456,
    topSongType: "Song",

    // relationships not also `included` are given a property with a null value
    topSong: null,

    // has many relationships are given a plural foreign key property
    instrumentIds: [789],

    // included records are gathered via relationships & placed in a collection:
    instruments: [
      { id: 789, type: "Instrument", name: "Piano" },
    ],

    links: {}
  },
  // response meta is available in case you need it
  meta: { parent: { id: "1", type: "Organization" } }
}

Contributing

Pull requests are welcome and encouraged! See the contributing guidelines for more information.