Step by Step Guide to Building a Donorbox API Integration in Python

Aug 16, 2024 • 6 minute read

Introduction

Hey there, fellow code wranglers! Ready to supercharge your fundraising efforts with some Python magic? Today, we're diving into the world of Donorbox API integration. This powerhouse tool will let you tap into donation data, manage campaigns, and process recurring donations like a pro. So, buckle up and let's get coding!

Prerequisites

Before we jump in, make sure you've got:

Python 3.7+
A Donorbox account with API credentials
Your favorite code editor (mine's got dark mode and enough caffeine stains to power a small city)

Setting up the environment

First things first, let's get our environment ready:

pip install requests python-dotenv

Now, create a .env file and add your Donorbox API credentials:

DONORBOX_API_KEY=your_api_key_here
DONORBOX_API_SECRET=your_api_secret_here

Basic API connection

Let's test the waters with a simple API call:

import os
import requests
from dotenv import load_dotenv

load_dotenv()

API_KEY = os.getenv('DONORBOX_API_KEY')
API_SECRET = os.getenv('DONORBOX_API_SECRET')

response = requests.get(
    'https://donorbox.org/api/v1/campaigns',
    auth=(API_KEY, API_SECRET)
)

print(response.json())

If you see your campaigns data, congratulations! You're now best friends with the Donorbox API.

Implementing key Donorbox API features

Retrieving donation data

Let's fetch those sweet, sweet donations:

def get_donations(campaign_id):
    response = requests.get(
        f'https://donorbox.org/api/v1/campaigns/{campaign_id}/donations',
        auth=(API_KEY, API_SECRET)
    )
    return response.json()

Creating and managing campaigns

Time to launch that world-changing campaign:

def create_campaign(name, goal):
    data = {
        'name': name,
        'goal_amount': goal
    }
    response = requests.post(
        'https://donorbox.org/api/v1/campaigns',
        auth=(API_KEY, API_SECRET),
        json=data
    )
    return response.json()

Processing recurring donations

Keep that money flowing with recurring donations:

def process_recurring_donations():
    response = requests.post(
        'https://donorbox.org/api/v1/recurring_donations/process',
        auth=(API_KEY, API_SECRET)
    )
    return response.json()

Error handling and best practices

Always be prepared for when things go sideways:

def api_request(method, endpoint, **kwargs):
    for attempt in range(3):
        try:
            response = requests.request(
                method,
                f'https://donorbox.org/api/v1/{endpoint}',
                auth=(API_KEY, API_SECRET),
                **kwargs
            )
            response.raise_for_status()
            return response.json()
        except requests.exceptions.RequestException as e:
            if attempt == 2:
                raise
            time.sleep(1)

Building a simple CLI tool

Let's wrap this all up in a neat little CLI package:

import argparse

def main():
    parser = argparse.ArgumentParser(description='Donorbox API CLI')
    parser.add_argument('action', choices=['list_campaigns', 'create_campaign', 'get_donations'])
    parser.add_argument('--name', help='Campaign name')
    parser.add_argument('--goal', type=float, help='Campaign goal amount')
    parser.add_argument('--campaign_id', help='Campaign ID')

    args = parser.parse_args()

    if args.action == 'list_campaigns':
        print(api_request('GET', 'campaigns'))
    elif args.action == 'create_campaign':
        print(create_campaign(args.name, args.goal))
    elif args.action == 'get_donations':
        print(get_donations(args.campaign_id))

if __name__ == '__main__':
    main()

Testing the integration

Don't forget to test! Here's a quick unit test to get you started:

import unittest

class TestDonorboxAPI(unittest.TestCase):
    def test_get_campaigns(self):
        campaigns = api_request('GET', 'campaigns')
        self.assertIsInstance(campaigns, list)
        self.assertTrue(len(campaigns) > 0)

if __name__ == '__main__':
    unittest.main()

Optimizing performance

Want to speed things up? Try some async magic:

import asyncio
import aiohttp

async def async_api_request(session, method, endpoint, **kwargs):
    async with session.request(method, f'https://donorbox.org/api/v1/{endpoint}', **kwargs) as response:
        return await response.json()

async def main():
    async with aiohttp.ClientSession(auth=aiohttp.BasicAuth(API_KEY, API_SECRET)) as session:
        campaigns = await async_api_request(session, 'GET', 'campaigns')
        print(campaigns)

asyncio.run(main())

Conclusion

And there you have it, folks! You've just built a robust Donorbox API integration in Python. From basic API calls to asynchronous requests, you're now equipped to handle donations like a champ. Remember, with great power comes great responsibility – use this integration wisely and watch those donations roll in!

Resources

Now go forth and fundraise like a Python pro! 🐍💰