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

``sh
yarn add @planningcenter/api-client
`

API Client

$3

`js
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).

$3

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

`js
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:

`js
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:

`js
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.

$3


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

$3

`js
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 }
}
}
}
}
})
`

$3

`js
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.

$3

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

#### Input
`javascript
import { transformRequestData } from "@planningcenter/api-client"

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

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




$3

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

#### Input
`js
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
`javascript
{
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.