@planningcenter/api-client

A Planning Center API client that will make you smile

Instillation and Setup

Install the package: yarn add @planningcenter/api-client

Expose your config on window (for now):

window.PCO_API_CLIENT_DEFAULT_APP = "services"
window.PCO_API_CLIENT_DEFAULT_VERSION = "2018-11-01"
window.PCO_API_CLIENT_ENV = "<%= Rails.env %>"

---

transformResponse

transformResponse takes an JSON API spec-adhering response and returns a lovely, transformed object or collection.

For example:

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

Will return a transformed object:

{
  // 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" },
  ],

  // response metadata is preserved in case you need it
  responseMeta: { parent: { id: "1", type: "Organization" } },
  links: {}
}

---

transformRequestData

transformRequestData takes an object with request parameters and transforms to a more api friendly format.

For example:

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

Will return a transformed object:

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

---

Request Methods

GET
There are a few things to be aware of with gets:

• It will walk pagination by defalut, you can turn this off by passing walk: false
• meta will be responseMeta
• if you need to spread the results and put them in a new array you will need to hold on to responseMeta
• fields are required

example:

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

POST
Fields are recommended, it will warn in dev if you do not pass them
example:

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

PATCH
Fields are recommended, it will warn in dev if you do not pass them
example:

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

DESTROY
same as what you would expect
example:

destroy({ url: /series/${seriesId} })

---

contributions are welcome, please read the contribution guidelines before submiting any pull requests

---

Write something nice in my guest book:

---

Have a good day!