Step by Step Guide to Building an Affinity API Integration in PHP

Introduction

Hey there, fellow developer! Ready to supercharge your PHP project with Affinity's powerful API? You're in the right place. We'll walk through building an integration that'll have you managing lists, persons, and organizations like a pro. Let's dive in!

Prerequisites

Before we get our hands dirty, make sure you've got:

• A PHP environment (7.4+ recommended)
• Composer installed
• Affinity API credentials (if you don't have these yet, no worries – we'll cover that)

Setting up the project

First things first, let's get our project off the ground:

mkdir affinity-integration
cd affinity-integration
composer init

Now, let's grab the HTTP client we'll use:

composer require guzzlehttp/guzzle

Authentication

Alright, time to get those API keys! Head over to your Affinity account settings and generate an API key. Got it? Great!

Let's set up a config file to keep things tidy:

// config.php
return [
    'api_key' => 'your_api_key_here',
    'base_url' => 'https://api.affinity.co/v1/'
];

Making API requests

Now for the fun part – let's make our first request:

// api.php
require 'vendor/autoload.php';
$config = require 'config.php';

$client = new GuzzleHttp\Client([
    'base_uri' => $config['base_url'],
    'headers' => [
        'Authorization' => 'Basic ' . base64_encode($config['api_key'] . ':'),
        'Content-Type' => 'application/json'
    ]
]);

$response = $client->get('lists');
$lists = json_decode($response->getBody(), true);

Core Affinity API endpoints

Affinity's API is your oyster. Here are the main endpoints you'll be working with:

• /lists
• /persons
• /organizations
• /fields

Each of these opens up a world of possibilities. Let's look at a quick example with persons:

$response = $client->get('persons');
$persons = json_decode($response->getBody(), true);

CRUD operations

Create, Read, Update, Delete – the four horsemen of API integration. Here's how to handle each:

Create

$newPerson = [
    'first_name' => 'John',
    'last_name' => 'Doe',
    'emails' => ['[email protected]']
];
$response = $client->post('persons', ['json' => $newPerson]);

Read

We've already seen this in action, but here it is again:

$response = $client->get('persons/123');
$person = json_decode($response->getBody(), true);

Update

$updatedData = ['title' => 'CEO'];
$response = $client->put('persons/123', ['json' => $updatedData]);

Delete

$response = $client->delete('persons/123');

Error handling and best practices

Always expect the unexpected. Wrap your requests in try-catch blocks:

try {
    $response = $client->get('persons/123');
} catch (GuzzleHttp\Exception\RequestException $e) {
    echo "Oops! " . $e->getMessage();
}

And don't forget about rate limits – Affinity's pretty generous, but it's always good to keep an eye on your usage.

Advanced features

Pagination

Affinity uses cursor-based pagination. Here's how to handle it:

$cursor = null;
do {
    $response = $client->get('persons', [
        'query' => ['cursor' => $cursor]
    ]);
    $data = json_decode($response->getBody(), true);
    // Process $data['persons']
    $cursor = $data['next_cursor'];
} while ($cursor);

Filtering and searching

Need to narrow down your results? Use query parameters:

$response = $client->get('persons', [
    'query' => ['term' => 'John']
]);

Testing the integration

Don't forget to test! Here's a simple PHPUnit test to get you started:

use PHPUnit\Framework\TestCase;

class AffinityApiTest extends TestCase
{
    public function testGetPersons()
    {
        // Your test code here
    }
}

Conclusion

And there you have it! You're now equipped to build a robust Affinity API integration in PHP. Remember, this is just the beginning – there's so much more you can do with Affinity's API. Keep exploring, keep coding, and most importantly, have fun with it!

Need more info? Check out Affinity's API docs for the full scoop. Happy coding!