Accessing CCB’s API Rate Limit Headers

Over the last few weeks, there’s been a bit of excitement in the world of Church Community Builder, also affectionately known as CCB.

I use “excitement” loosely as many churches using CCB’s API were informed about CCB implementing a new per-minute rate limiting policy in addition to its per-day allotment of 10,000 calls per day — which they hope to retire sooner rather than later, yet it’ll remain in place for now.

As of August 20th, this new rate limiting strategy aims to restrict how many times per minute an API user can access an individual API Service — noted in New API Rate Limiting documentation.

So, what does this truly mean to you, and more importantly, how does this new strategy impact developed applications and environments using CCB’s API? 🤔

In short, rate limiting is not a bad thing. Rate limiting truly aims for the following:

  • Provide greater data security controls in event of a data breach
  • Protect APIs from overuse by limiting how often each user can call the API
  • Reduce, if not eliminate, the opportunity from inadvertent and malicious overuse that may lead to API request spiking

There are likely other benefits from rate limiting, but these are simply a few that come to mind.

Who and what might this new change impact the most?

Churches having developed multi-threaded or multi-processing scripts to get or post data to and from CCB using the API are greatly impacted by this new policy.

If you don’t use multi-threaded processes, then this new change is less likely to impact your church. But don’t think you’re in the clear just yet.

If your church performs any of the following tasks, to name just a few that come to mind, then it’s recommended to review, adjust and adhere to the CCB’s API rate limiting policy:

  • Batching of any sort
  • Nightly attendance reporting
  • Nightly or incremental backups
  • Custom community group applications
  • Mobile applications

No matter if single or multi-thread development, you’re likely going to notice and realized hampered performance for development efforts simultaneously and consecutively requesting multiple API Services.

What actions should be taken to comply?

If an API user chooses to take no action regarding the new api rate limiting policy, then you’re likely going to run afoul and have your API access temporarily or permanently revoked for your church’s subdomain.

As stated in the API rate-limiting documentation, CCB is now provides HTTP Headers and Response Codes. Plan accordingly to have logic implemented within your software or application that takes into account rate-limiting attributes and their respective limits (see documentation).

Code Example of Logic to Incorporate API Rate-Limit Headers

To prepare for the new rate limiting restrictions per documentation, CCB has provided a rate_limit_test API Service to test the rate limiting service without penalty.

Nevertheless, if you’re using code from this website, then a few modifications to the general.php file are needed to incorporate the appropriate API rate-limit logic.

If Using Windows

If you’re using PHP in a Windows environment, then you’ll need to ensure the following is added to the general.php file in the cURL transfer setup options of the ccbDetails function.

The above curl_setopt options of CURLOPT_HEADER and CURLOPT_NOBODY ensure HTTP Headers and Response Codes are returned.

If Using *nix

If you’re using PHP in a Unix or Linux environment, then you’ll need to ensure the following is added to the *nix section of the ccbDetails function in the general.php.

Add “-i” to the executed curl command using shell_exec ensure HTTP Headers and Response Codes are returned.

The last change to be made in the general.php file occurs before returning the transformed XML using PHP’s built-in SimpleXMLElement method. The code looks as follows:

In between the $response_object variables, add the following code (read comments for explanation):

Special hat tip to Jon Diercks for proposed logic and solution using the HTTP Headers.

If desired, you could also return the headers with the XML response as an array, and then access the headers in your script should you make additional API calls.

This could come in handy for scripts that iterate using for or foreach loops.

In closing, the good news is that you have from now until August 20th to figure out the appropriate action to take for your various CCB API development efforts.

And it goes without saying, but certainly feel free to contact us should you need assistance assessing a plan of action for your CCB API development efforts.

Thanks and that’s all for now!


Please comment if this tutorial has helped you.