pco_api 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 6389ae53bf68d7cd03849bc44f51776dd0c8705a
+  data.tar.gz: d0a6ef6c002c42787f00e8e3525f407959eebbf0
+SHA512:
+  metadata.gz: edad5401340bd1a6c87f7cc360c8fc09af04d2eebc61de5fed0eba57dbc8d92ce6db43253d810d786b25c475a5e8b17367e42af5d475d4276573034ca90bc374
+  data.tar.gz: ff3c7b758c84e4331b16356689111ff717c1bf322fd2fa2888a4af3838c59360c56263e1e020c18b0a9884fcf26f8af3726d973b35d94b4928651bfc9782f0e4

data/README.md

@@ -0,0 +1,208 @@
+# pco_api
+
+`pco_api` is a Rubygem that provides a simple wrapper around our RESTful JSON api at https://api.planningcenteronline.com.
+
+## Installation
+
+```
+gem install pco_api
+```
+
+## Usage
+
+1. Create a new API object, passing in your credentials (either HTTP Basic or OAuth2 access token):
+
+    ```ruby
+    # authenticate with HTTP Basic:
+    api = PCO::API.new(basic_auth_token: 'token', basic_auth_secret: 'secret')
+    # ...or authenticate with an OAuth2 access token (use the 'oauth2' gem to obtain the token)
+    api = PCO::API.new(oauth_access_token: 'token')
+    ```
+
+2. Chain path elements together as method calls.
+
+    ```ruby
+    api.people.v1.households
+    # /people/v1/households
+    ```
+
+3. For IDs, treat the object like a hash (use square brackets).
+
+    ```ruby
+    api.people.v1.households[1]
+    # /people/v1/households/1
+    ```
+
+4. To execute the request, use `get`, `post`, `patch`, or `delete`, optionally passing arguments.
+
+    ```ruby
+    api.people.v1.households.get(order: 'name')
+    # GET /people/v1/households?order=name
+    ```
+
+## Example
+
+```ruby
+require 'pco_api'
+
+api = PCO::API.new(auth_token: 'token', auth_secret: 'secret')
+api.people.v1.people.get(order: 'last_name')
+```
+
+...which returns something like:
+
+```ruby
+{
+  "links" => {
+    "self" => "https://api.planningcenteronline.com/people/v1/people?order=last_name",
+    "next" => "https://api.planningcenteronline.com/people/v1/people?offset=25&order=last_name"
+  },
+  "data"=> [
+    {
+      "type" => "Person",
+      "id" => "271",
+      "first_name" => "Jean",
+      "middle_name" => nil,
+      "last_name" => "Abernathy",
+      "birthdate" => "1885-01-01",
+      "anniversary" => nil,
+      "gender" => "F",
+      "grade" => -1,
+      "child" => false,
+      "status" => "active",
+      "school_type" => nil,
+      "graduation_year" => nil,
+      "site_administrator" => false,
+      "people_permissions" => nil,
+      "created_at" => "2015-04-01T20:18:22Z",
+      "updated_at" => "2015-04-10T18:59:51Z",
+      "avatar" => nil,
+      "links" => {
+        "self" => "https://api.planningcenteronline.com/people/v1/people/271"
+      }
+    },
+    # ...
+  ],
+  "meta" => {
+    "total_count" => 409,
+    "count" => 25,
+    "next" => {
+      "offset" => 25
+    },
+    "orderable_by" => [
+      "first_name",
+      "middle_name",
+      "last_name",
+      "birthdate",
+      "anniversary",
+      "gender",
+      "grade",
+      "child",
+      "status",
+      "school_type",
+      "graduation_year",
+      "site_administrator",
+      "people_permissions",
+      "created_at",
+      "updated_at"
+    ],
+    "filterable_by" => [
+      "first_name",
+      "middle_name",
+      "last_name",
+      "birthdate",
+      "anniversary",
+      "gender",
+      "grade",
+      "child",
+      "status",
+      "school_type",
+      "graduation_year",
+      "site_administrator",
+      "people_permissions",
+      "created_at",
+      "updated_at"
+    ],
+    "can_include" => [
+      "emails",
+      "addresses",
+      "phone_numbers",
+      "households",
+      "school",
+      "inactive_reason",
+      "marital_status",
+      "name_prefix",
+      "name_suffix",
+      "field_data",
+      "apps"
+    ]
+  }
+}
+```
+
+## get()
+
+`get()` works for a collection (index) and a single resource (show).
+
+```ruby
+# collection
+api.people.v1.people.get(order: 'last_name')
+# => { data: array_of_resources }
+
+# single resource
+api.people.v1.people[1].get
+# => { data: resource_hash }
+```
+
+## post()
+
+`post()` sends a POST request to create a new resource. You *must* wrap your resource with
+a `{ data: { ... } }` hash.
+
+```ruby
+api.people.v1.people.post(data: { first_name: 'Tim', last_name: 'Morgan' })
+# => { data: resource_hash }
+```
+
+## patch()
+
+`patch()` sends a PATCH request to update an existing resource. You *must* wrap your resource with
+a `{ data: { ... } }` hash.
+
+```ruby
+api.people.v1.people[1].patch(data: { first_name: 'Tim', last_name: 'Morgan' })
+# => { data: resource_hash }
+```
+
+## delete()
+
+`delete()` sends a DELETE request to delete an existing resource. This method returns `true` if the delete was successful.
+
+```ruby
+api.people.v1.people[1].delete
+# => true
+```
+
+## Errors
+
+The following errors may be raised, which you should rescue in most circumstances.
+
+| HTTP Status Codes   | Error Class                     |
+| ------------------- | ------------------------------- |
+| 404                 | `PCO::API::Errors::NotFound`    |
+| 4xx (except 404)    | `PCO::API::Errors::ClientError` |
+| 5xx                 | `PCO::API::Errors::ServerError` |
+
+The exception class has the following methods:
+
+| Method  | Content                                         |
+| ------- | ----------------------------------------------- |
+| status  | HTTP status code returned by the server         |
+| message | the body of the response returned by the server |
+
+The `message` will usually be a hash (produced by parsing the response JSON),
+but in the case of some server errors, may be a string containing the raw response.
+
+## Copyright & License
+
+Copyright 2015, Ministry Centered Technologies. Licensed MIT.

data/lib/pco/api.rb

@@ -0,0 +1,11 @@
+require_relative 'api/endpoint'
+require_relative 'api/errors'
+
+module PCO
+  module API
+    module_function
+    def new(*args)
+      Endpoint.new(*args)
+    end
+  end
+end

data/lib/pco/api/endpoint.rb

@@ -0,0 +1,108 @@
+require 'faraday'
+require 'faraday_middleware'
+
+module PCO
+  module API
+    URL = 'https://api.planningcenteronline.com'
+
+    class Endpoint
+      attr_reader :url, :last_result
+
+      def initialize(url: URL, oauth_access_token: nil, basic_auth_token: nil, basic_auth_secret: nil, connection: nil)
+        @url = url
+        @oauth_access_token = oauth_access_token
+        @basic_auth_token = basic_auth_token
+        @basic_auth_secret = basic_auth_secret
+        @connection = connection || _build_connection
+        @cache = {}
+      end
+
+      def method_missing(method_name, *_args)
+        _build_endpoint(method_name.to_s)
+      end
+
+      def [](id)
+        _build_endpoint(id.to_s)
+      end
+
+      def respond_to?(method_name)
+        endpoint = _build_endpoint(method_name.to_s)
+        begin
+          endpoint.get
+        rescue Errors::NotFound
+          false
+        else
+          true
+        end
+      end
+
+      def get(params = {})
+        @last_result = @connection.get(@url, params)
+        _build_response(@last_result)
+      end
+
+      def post(body = {})
+        @last_result = @connection.post(@url) do |req|
+          req.body = body.to_json
+        end
+        _build_response(@last_result)
+      end
+
+      def patch(body = {})
+        @last_result = @connection.patch(@url) do |req|
+          req.body = body.to_json
+        end
+        _build_response(@last_result)
+      end
+
+      def delete
+        @last_result = @connection.delete(@url)
+        if @last_result.status == 204
+          true
+        else
+          _build_response(@last_result)
+        end
+      end
+
+      private
+
+      def _build_response(result)
+        case result.status
+        when 200..299
+          result.body
+        when 404
+          fail Errors::NotFound, result
+        when 400..499
+          fail Errors::ClientError, result
+        when 500..599
+          fail Errors::ServerError, result
+        else
+          fail "unknown status #{result.status}"
+        end
+      end
+
+      def _build_endpoint(path)
+        @cache[path] ||= begin
+          self.class.new(
+            url: File.join(url, path.to_s),
+            connection: @connection
+          )
+        end
+      end
+
+      def _build_connection
+        Faraday.new(url: url) do |faraday|
+          faraday.adapter :excon
+          faraday.response :json, content_type: /\bjson$/
+          if @basic_auth_token && @basic_auth_secret
+            faraday.basic_auth @basic_auth_token, @basic_auth_secret
+          elsif @oauth_access_token
+            faraday.headers['Authorization'] = "Bearer #{@oauth_access_token}"
+          else
+            fail Errors::AuthRequiredError, "You must specify either HTTP basic auth credentials or an OAuth2 access token."
+          end
+        end
+      end
+    end
+  end
+end

data/lib/pco/api/errors.rb

@@ -0,0 +1,28 @@
+module PCO
+  module API
+    module Errors
+      class AuthRequiredError < StandardError; end
+
+      class BaseError < StandardError
+        attr_reader :status
+
+        def initialize(response)
+          @status = response.status
+          @message = response.body
+        end
+
+        def to_s
+          @message
+        end
+
+        def inspect
+          "<#{self.class.name} status=#{@status} message=#{@message}>"
+        end
+      end
+
+      class NotFound    < BaseError; end
+      class ClientError < BaseError; end
+      class ServerError < BaseError; end
+    end
+  end
+end

data/lib/pco/api/version.rb

@@ -0,0 +1,5 @@
+module PCO
+  module API
+    VERSION = '1.0.0'
+  end
+end

data/lib/pco_api.rb

@@ -0,0 +1 @@
+require_relative 'pco/api'

data/spec/pco/api/endpoint_spec.rb

@@ -0,0 +1,200 @@
+require_relative '../../spec_helper'
+require 'json'
+
+describe PCO::API::Endpoint do
+  let(:base) { described_class.new(auth_token: 'token', auth_secret: 'secret') }
+
+  subject { base }
+
+  describe '#method_missing' do
+    before do
+      @result = subject.people.v1
+    end
+
+    it 'returns a wrapper object with updated url' do
+      expect(@result).to be_a(described_class)
+      expect(@result.url).to match(%r{/people/v1$})
+    end
+  end
+
+  describe '#[]' do
+    before do
+      @result = subject.people.v1.people[1]
+    end
+
+    it 'returns a wrapper object with updated url' do
+      expect(@result).to be_a(described_class)
+      expect(@result.url).to match(%r{/people/v1/people/1$})
+    end
+  end
+
+  describe '#get' do
+    context 'given a good URL' do
+      subject { base.people.v1 }
+
+      let(:result) do
+        {
+          'type'  => 'Organization',
+          'id'    => '1',
+          'name'  => 'Ministry Centered Technologies',
+          'links' => {}
+        }
+      end
+
+      before do
+        stub_request(:get, 'https://api.planningcenteronline.com/people/v1')
+          .to_return(status: 200, body: { data: result }.to_json, headers: { 'Content-Type' => 'application/vnd.api+json' })
+        @result = subject.get
+      end
+
+      it 'returns the result of making a GET request to the endpoint' do
+        expect(@result).to be_a(Hash)
+        expect(@result['data']).to eq(result)
+      end
+    end
+
+    context 'given a non-existent URL' do
+      subject { base.people.v1.non_existent }
+
+      let(:result) do
+        {
+          'status'  => 404,
+          'message' => 'Resource Not Found'
+        }
+      end
+
+      before do
+        stub_request(:get, 'https://api.planningcenteronline.com/people/v1/non_existent')
+          .to_return(status: 404, body: result.to_json, headers: { 'Content-Type' => 'application/vnd.api+json' })
+      end
+
+      it 'raises a NotFound error' do
+        expect {
+          subject.get
+        }.to raise_error(PCO::API::Errors::NotFound)
+      end
+    end
+
+    context 'given a client error' do
+      subject { base.people.v1.error }
+
+      let(:result) do
+        {
+          'status'  => 400,
+          'message' => 'Bad request'
+        }
+      end
+
+      before do
+        stub_request(:get, 'https://api.planningcenteronline.com/people/v1/error')
+          .to_return(status: 400, body: result.to_json, headers: { 'Content-Type' => 'application/vnd.api+json' })
+      end
+
+      it 'raises a ClientError error' do
+        expect {
+          subject.get
+        }.to raise_error(PCO::API::Errors::ClientError)
+      end
+    end
+
+    context 'given a server error' do
+      subject { base.people.v1.error }
+
+      let(:result) do
+        {
+          'status'  => 500,
+          'message' => 'System error has occurred'
+        }
+      end
+
+      before do
+        stub_request(:get, 'https://api.planningcenteronline.com/people/v1/error')
+          .to_return(status: 500, body: result.to_json, headers: { 'Content-Type' => 'application/vnd.api+json' })
+      end
+
+      it 'raises a ServerError error' do
+        expect {
+          subject.get
+        }.to raise_error(PCO::API::Errors::ServerError)
+      end
+    end
+  end
+
+  describe '#post' do
+    subject { base.people.v1.people }
+
+    let(:resource) do
+      {
+        'type'       => 'Person',
+        'first_name' => 'Tim',
+        'last_name'  => 'Morgan'
+      }
+    end
+
+    let(:result) do
+      {
+        'type'       => 'Person',
+        'id'         => '1',
+        'first_name' => 'Tim',
+        'last_name'  => 'Morgan'
+      }
+    end
+
+    before do
+      stub_request(:post, 'https://api.planningcenteronline.com/people/v1/people')
+        .to_return(status: 201, body: { data: result }.to_json, headers: { 'Content-Type' => 'application/vnd.api+json' })
+      @result = subject.post(data: resource)
+    end
+
+    it 'returns the result of making a POST request to the endpoint' do
+      expect(@result).to be_a(Hash)
+      expect(@result['data']).to eq(result)
+    end
+  end
+
+  describe '#patch' do
+    subject { base.people.v1.people[1] }
+
+    let(:resource) do
+      {
+        'type'       => 'Person',
+        'first_name' => 'Tim',
+        'last_name'  => 'Morgan'
+      }
+    end
+
+    let(:result) do
+      {
+        'type'       => 'Person',
+        'id'         => '1',
+        'first_name' => 'Tim',
+        'last_name'  => 'Morgan'
+      }
+    end
+
+    before do
+      stub_request(:patch, 'https://api.planningcenteronline.com/people/v1/people/1')
+        .to_return(status: 200, body: { data: result }.to_json, headers: { 'Content-Type' => 'application/vnd.api+json' })
+      @result = subject.patch(data: resource)
+    end
+
+    it 'returns the result of making a PATCH request to the endpoint' do
+      expect(@result).to be_a(Hash)
+      expect(@result['data']).to eq(result)
+    end
+  end
+
+  describe '#delete' do
+    subject { base.people.v1.people[1] }
+
+    before do
+      stub_request(:delete, 'https://api.planningcenteronline.com/people/v1/people/1')
+        .to_return(status: 204, body: '')
+      @result = subject.delete
+    end
+
+    it 'returns true' do
+      expect(@result).to eq(true)
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,18 @@
+require 'webmock/rspec'
+
+require_relative '../lib/pco_api'
+
+RSpec.configure do |config|
+  config.expect_with :rspec do |expectations|
+    expectations.include_chain_clauses_in_custom_matcher_descriptions = true
+  end
+
+  config.mock_with :rspec do |mocks|
+    mocks.verify_partial_doubles = true
+  end
+
+  config.color = true
+  config.order = 'random'
+  config.filter_run focus: true
+  config.run_all_when_everything_filtered = true
+end

metadata

@@ -0,0 +1,136 @@
+--- !ruby/object:Gem::Specification
+name: pco_api
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Planning Center Online
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2015-06-03 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.9.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.9.1
+- !ruby/object:Gem::Dependency
+  name: faraday_middleware
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.9.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.9.1
+- !ruby/object:Gem::Dependency
+  name: excon
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.30.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.30.0
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.2.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.2.0
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.21.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.21.0
+- !ruby/object:Gem::Dependency
+  name: pry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.10.1
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.10.1
+description: Ruby wrapper for the RESTful PCO API
+email: 
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/pco/api.rb
+- lib/pco/api/endpoint.rb
+- lib/pco/api/errors.rb
+- lib/pco/api/version.rb
+- lib/pco_api.rb
+- spec/pco/api/endpoint_spec.rb
+- spec/spec_helper.rb
+homepage: https://github.com/planningcenter/pco_api_ruby
+licenses: []
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.4.6
+signing_key: 
+specification_version: 4
+summary: Ruby wrapper for the RESTful PCO API
+test_files:
+- spec/pco/api/endpoint_spec.rb
+- spec/spec_helper.rb