restforce 5.1.1 → 5.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 68aba674731ec407d63a766c8bcf13a6a243e757e89b32c8bed07c07a2ee2a9e
-  data.tar.gz: 1529b415da1c3d34ff477aea87116d147d5e2bd3e74ebde236ef9292545fad54
+  metadata.gz: f30c54c95fc530b6278faf751728b2793971c8aa0e43862f6719753a1d62d4fa
+  data.tar.gz: c7ac3a654170e2cb883325b12f4e6315d0c0423f9673142c93c87cf5de2003b8
 SHA512:
-  metadata.gz: 5fc24ced1a9e38b622040d0b51ea3cd3aa2d4afc994ee41a8825ee2038c1f7379c56c2a32044a938102fe47030f02183549bdd91837ffab88320d99af13d27c5
-  data.tar.gz: 1a0be3c634cb0b9bcea1b38463b09e62e54ceee49b44e30e852e42c14c91761eff4cf8a6a786611682cb0ba309704d85243499c00358b6e411ded15e805f421e
+  metadata.gz: 4a731ebfe6e755b66479f8e85434a017d50a81c084f048e1454f3714bb047c36f8362976c904a91890b8f62099a3238689fe93f200468670b8f4dafc51cb5aa5
+  data.tar.gz: f5e8cd87fc4eccd486828627dfa1c769107e5869f7cf60088d5c7ee2cde2207d9bf33794a4f1639b98cfccfee54734d583dcbdbea8d841442a7086ff00b9e315

data/CHANGELOG.md

@@ -1,3 +1,8 @@
+## 5.2.0 (Oct 15, 2021)
+
+* Add support for Salesforce's Composite API and Composite Batch API (@meenie, @amacdougall)
+* Improve the performance of counting numbers of query results with `Restforce::Collection#count`, avoiding unnecessary API requests (@jhass)
+
 ## 5.1.1 (Oct 13, 2021)
 
 * Handle the `INVALID_REPLICATION_DATE` error returned by Salesforce (@michaelwnyc)

data/README.md

@@ -12,6 +12,8 @@ Features include:
 * Support for parent-to-child relationships.
 * Support for aggregate queries.
 * Support for the [Streaming API](#streaming)
+* Support for the [Composite API](#composite-api)
+* Support for the [Composite Batch API](#composite-batch-api)
 * Support for the GetUpdated API
 * Support for blob data types.
 * Support for GZIP compression.
@@ -25,7 +27,7 @@ Features include:
 
 Add this line to your application's Gemfile:
 
-    gem 'restforce', '~> 5.1.1'
+    gem 'restforce', '~> 5.2.0'
 
 And then execute:
 
@@ -573,6 +575,52 @@ end
 Boom, you're now receiving push notifications when Accounts are
 created/updated.
 
+#### Composite API
+
+Restforce supports the [Composite API](https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/resources_composite_composite.htm).
+This feature permits the user to send a composite object—that is, a complex
+object with nested children—in a single API call. Up to 25 requests may be
+included in a single composite.
+
+Note that `GET` is not yet implemented for this API.
+
+```ruby
+# build up an array of requests:
+requests << {
+  method: :update,
+  sobject: sobject, # e.g. "Contact"
+  reference_id: reference_id,
+  data: data
+}
+
+# send every 25 requests as a subrequest in a single composite call
+requests.each_slice(25).map do |req_slice|
+  client.composite do |subrequest|
+    req_slice.each do |r|
+      subrequest.send *r.values
+    end
+  end
+end
+
+# note that we're using `map` to return an array of each responses to each
+# composite call; 100 requests will produce 4 responses
+```
+
+#### Composite Batch API
+
+Restforce supports the [Composite Batch API](https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/resources_composite_batch.htm).
+This feature permits up to 25 subrequests in a single request, though each
+subrequest counts against the API limit. On the other hand, it has fewer
+limitations than the Composite API.
+
+```
+client.batch do |subrequests|
+  subrequests.create('Object', name: 'test')
+  subrequests.update('Object', id: '123', name: 'test')
+  subrequests.destroy('Object', '123')
+end
+```
+
 #### Replaying Events
 
 Since API version 37.0, Salesforce stores events for 24 hours and they can be

data/lib/restforce/abstract_client.rb

@@ -8,5 +8,6 @@ module Restforce
     include Restforce::Concerns::Caching
     include Restforce::Concerns::API
     include Restforce::Concerns::BatchAPI
+    include Restforce::Concerns::CompositeAPI
   end
 end

data/lib/restforce/collection.rb

@@ -27,12 +27,26 @@ module Restforce
       @raw_page['records'].size
     end
 
-    # Return the size of the Collection without making any additional requests.
+    # Return the number of items in the Collection without making any additional
+    # requests and going through all of the pages of results, one by one. Instead,
+    # we can rely on the total count of results which Salesforce returns.
     def size
       @raw_page['totalSize']
     end
     alias length size
 
+    def count(*args)
+      # By default, `Enumerable`'s `#count` uses `#each`, which means going through all
+      # of the pages of results, one by one. Instead, we can use `#size` which we have
+      # already overridden to work in a smarter, more efficient way. This only works for
+      # the simple version of `#count` with no arguments. When called with an argument or
+      # a block, you need to know what the items in the collection actually are, so we
+      # call `super` and end up iterating through each item in the collection.
+      return size unless block_given? || !args.empty?
+
+      super
+    end
+
     # Returns true if the size of the Collection is zero.
     def empty?
       size.zero?

data/lib/restforce/concerns/composite_api.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require 'restforce/concerns/verbs'
+
+module Restforce
+  module Concerns
+    module CompositeAPI
+      extend Restforce::Concerns::Verbs
+
+      define_verbs :post
+
+      def composite(all_or_none: false, collate_subrequests: false)
+        subrequests = Subrequests.new(options)
+        yield(subrequests)
+
+        if subrequests.requests.length > 25
+          raise ArgumentError, 'Cannot have more than 25 subrequests.'
+        end
+
+        properties = {
+          compositeRequest: subrequests.requests,
+          allOrNone: all_or_none,
+          collateSubrequests: collate_subrequests
+        }
+        response = api_post('composite', properties.to_json)
+
+        results = response.body['CompositeResponse']
+        has_errors = results.any? { |result| result['HttpStatusCode'].digits.last == 4 }
+        if all_or_none && has_errors
+          last_error_index = results.rindex { |result| result['HttpStatusCode'] != 412 }
+          last_error = results[last_error_index]
+          raise CompositeAPIError, last_error['Body'][0]['errorCode']
+        end
+
+        results
+      end
+
+      def composite!(collate_subrequests: false, &block)
+        composite(all_or_none: true, collate_subrequests: collate_subrequests, &block)
+      end
+
+      class Subrequests
+        def initialize(options)
+          @options = options
+          @requests = []
+        end
+        attr_reader :options, :requests
+
+        def create(sobject, reference_id, attrs)
+          requests << {
+            method: 'POST',
+            url: composite_api_path(sobject),
+            body: attrs,
+            referenceId: reference_id
+          }
+        end
+
+        def update(sobject, reference_id, attrs)
+          id = attrs.fetch(attrs.keys.find { |k, _v| k.to_s.casecmp?('id') }, nil)
+          raise ArgumentError, 'Id field missing from attrs.' unless id
+
+          attrs_without_id = attrs.reject { |k, _v| k.to_s.casecmp?('id') }
+          requests << {
+            method: 'PATCH',
+            url: composite_api_path("#{sobject}/#{id}"),
+            body: attrs_without_id,
+            referenceId: reference_id
+          }
+        end
+
+        def destroy(sobject, reference_id, id)
+          requests << {
+            method: 'DELETE',
+            url: composite_api_path("#{sobject}/#{id}"),
+            referenceId: reference_id
+          }
+        end
+
+        def upsert(sobject, reference_id, ext_field, attrs)
+          raise ArgumentError, 'External id field missing.' unless ext_field
+
+          ext_id = attrs.fetch(attrs.keys.find do |k, _v|
+            k.to_s.casecmp?(ext_field.to_s)
+          end, nil)
+          raise ArgumentError, 'External id missing from attrs.' unless ext_id
+
+          attrs_without_ext_id = attrs.reject { |k, _v| k.to_s.casecmp?(ext_field) }
+          requests << {
+            method: 'PATCH',
+            url: composite_api_path("#{sobject}/#{ext_field}/#{ext_id}"),
+            body: attrs_without_ext_id,
+            referenceId: reference_id
+          }
+        end
+
+        private
+
+        def composite_api_path(path)
+          "/services/data/v#{options[:api_version]}/sobjects/#{path}"
+        end
+      end
+    end
+  end
+end

data/lib/restforce/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Restforce
-  VERSION = '5.1.1'
+  VERSION = '5.2.0'
 end

data/lib/restforce.rb

@@ -32,6 +32,7 @@ module Restforce
     autoload :Base,           'restforce/concerns/base'
     autoload :API,            'restforce/concerns/api'
     autoload :BatchAPI,       'restforce/concerns/batch_api'
+    autoload :CompositeAPI,   'restforce/concerns/composite_api'
   end
 
   module Data
@@ -48,6 +49,7 @@ module Restforce
   UnauthorizedError   = Class.new(Faraday::ClientError)
   APIVersionError     = Class.new(Error)
   BatchAPIError       = Class.new(Error)
+  CompositeAPIError   = Class.new(Error)
 
   # Inherit from Faraday::ResourceNotFound for backwards-compatibility
   # Consumers of this library that rescue and handle Faraday::ResourceNotFound

data/spec/unit/concerns/composite_api_spec.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+describe Restforce::Concerns::CompositeAPI do
+  let(:endpoint) { 'composite' }
+
+  before do
+    client.should_receive(:options).and_return(api_version: 38.0)
+  end
+
+  shared_examples_for 'composite requests' do
+    it '#create' do
+      client.
+        should_receive(:api_post).
+        with(endpoint, { compositeRequest: [
+          {
+            method: 'POST',
+            url: '/services/data/v38.0/sobjects/Object',
+            body: { name: 'test' },
+            referenceId: 'create_ref'
+          }
+        ], allOrNone: all_or_none, collateSubrequests: false }.to_json).
+        and_return(response)
+
+      client.send(method) do |subrequests|
+        subrequests.create('Object', 'create_ref', name: 'test')
+      end
+    end
+
+    it '#update' do
+      client.
+        should_receive(:api_post).
+        with(endpoint, { compositeRequest: [
+          {
+            method: 'PATCH',
+            url: '/services/data/v38.0/sobjects/Object/123',
+            body: { name: 'test' },
+            referenceId: 'update_ref'
+          }
+        ], allOrNone: all_or_none, collateSubrequests: false }.to_json).
+        and_return(response)
+
+      client.send(method) do |subrequests|
+        subrequests.update('Object', 'update_ref', id: '123', name: 'test')
+      end
+    end
+
+    it '#destroy' do
+      client.
+        should_receive(:api_post).
+        with(endpoint, { compositeRequest: [
+          {
+            method: 'DELETE',
+            url: '/services/data/v38.0/sobjects/Object/123',
+            referenceId: 'destroy_ref'
+          }
+        ], allOrNone: all_or_none, collateSubrequests: false }.to_json).
+        and_return(response)
+
+      client.send(method) do |subrequests|
+        subrequests.destroy('Object', 'destroy_ref', '123')
+      end
+    end
+
+    it '#upsert' do
+      client.
+        should_receive(:api_post).
+        with(endpoint, { compositeRequest: [
+          {
+            method: 'PATCH',
+            url: '/services/data/v38.0/sobjects/Object/extIdField__c/456',
+            body: { name: 'test' },
+            referenceId: 'upsert_ref'
+          }
+        ], allOrNone: all_or_none, collateSubrequests: false }.to_json).
+        and_return(response)
+
+      client.send(method) do |subrequests|
+        subrequests.upsert('Object', 'upsert_ref', 'extIdField__c',
+                           extIdField__c: '456', name: 'test')
+      end
+    end
+
+    it 'multiple subrequests' do
+      client.
+        should_receive(:api_post).
+        with(endpoint, { compositeRequest: [
+          {
+            method: 'POST',
+            url: '/services/data/v38.0/sobjects/Object',
+            body: { name: 'test' },
+            referenceId: 'create_ref'
+          },
+          {
+            method: 'PATCH',
+            url: '/services/data/v38.0/sobjects/Object/123',
+            body: { name: 'test' },
+            referenceId: 'update_ref'
+          },
+          {
+            method: 'DELETE',
+            url: '/services/data/v38.0/sobjects/Object/123',
+            referenceId: 'destroy_ref'
+          }
+        ], allOrNone: all_or_none, collateSubrequests: false }.to_json).
+        and_return(response)
+
+      client.send(method) do |subrequests|
+        subrequests.create('Object', 'create_ref', name: 'test')
+        subrequests.update('Object', 'update_ref', id: '123', name: 'test')
+        subrequests.destroy('Object', 'destroy_ref', '123')
+      end
+    end
+
+    it 'fails if more than 25 requests' do
+      expect do
+        client.send(method) do |subrequests|
+          26.times do |i|
+            subrequests.upsert('Object', "upsert_ref_#{i}", 'extIdField__c',
+                               extIdField__c: '456', name: 'test')
+          end
+        end
+      end.to raise_error(ArgumentError)
+    end
+  end
+
+  describe '#composite' do
+    let(:method) { :composite }
+    let(:all_or_none) { false }
+    let(:response) { double('Faraday::Response', body: { 'CompositeResponse' => [] }) }
+    it_behaves_like 'composite requests'
+  end
+
+  describe '#composite!' do
+    let(:method) { :composite! }
+    let(:all_or_none) { true }
+    let(:response) do
+      double('Faraday::Response', body: { 'CompositeResponse' => [] })
+    end
+    it_behaves_like 'composite requests'
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: restforce
 version: !ruby/object:Gem::Version
-  version: 5.1.1
+  version: 5.2.0
 platform: ruby
 authors:
 - Tim Rogers
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-10-13 00:00:00.000000000 Z
+date: 2021-10-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -121,6 +121,7 @@ files:
 - lib/restforce/concerns/batch_api.rb
 - lib/restforce/concerns/caching.rb
 - lib/restforce/concerns/canvas.rb
+- lib/restforce/concerns/composite_api.rb
 - lib/restforce/concerns/connection.rb
 - lib/restforce/concerns/picklists.rb
 - lib/restforce/concerns/streaming.rb
@@ -209,6 +210,7 @@ files:
 - spec/unit/concerns/batch_api_spec.rb
 - spec/unit/concerns/caching_spec.rb
 - spec/unit/concerns/canvas_spec.rb
+- spec/unit/concerns/composite_api_spec.rb
 - spec/unit/concerns/connection_spec.rb
 - spec/unit/concerns/streaming_spec.rb
 - spec/unit/config_spec.rb
@@ -310,6 +312,7 @@ test_files:
 - spec/unit/concerns/batch_api_spec.rb
 - spec/unit/concerns/caching_spec.rb
 - spec/unit/concerns/canvas_spec.rb
+- spec/unit/concerns/composite_api_spec.rb
 - spec/unit/concerns/connection_spec.rb
 - spec/unit/concerns/streaming_spec.rb
 - spec/unit/config_spec.rb