A Planning Center JavaScript API client that will make you smile
View the classic README here.
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" } }
}
``