Intro

In today's fast-paced world of software development, integrating your application with external APIs is virtually inevitable. However, each API comes with its own unique set of integration challenges. To maintain a clean and organized codebase, while also segregating the business logic of your application from the intricacies of third-party API interactions, consider the invaluable tool that is Saloon. This PHP package, compatible not only as a standalone solution but also as a seamless Laravel package, can help you architect your solution in an extensible and efficient manner.

If you want to know what are the advantages of using Saloon, you can read my article 5 reasons why you should use Saloon to connect to third party API. Now, assuming you're already acquainted with Saloon, let's delve into a real-world use case that beautifully illustrates how Saloon can transform your integration process in mere minutes.

The idea 💡

The story begins with my decision to use Beehiiv for my newsletter. Although I had no immediate plans to subscribe to their paid plan, I was drawn in by their attractive offering and the overall positive user experience. The prospect of having a customized widget on my website, giving me full control over the subscription box text, was particularly appealing.

Beehiiv offered APIs for adding subscribers, and that's where Saloon came into play. The integration process was smooth as silk. When a website visitor decided to subscribe, Next.js initiated a server-side call to my trusty Laravel application, the backbone of my blog. Like a well-oiled machine, Laravel took care of all the intricate communication with Beehiiv.

Every good thing comes to an end

However, the tide turned when my Beehiiv trial period came to a close. I must confess that Beehiiv's email notifications were nothing short of impressive. Just 24 hours before my trial expired, I received a comprehensive email outlining all the incredible features I'd be forfeiting if I chose not to continue with a paid plan. It was a wake-up call—I realized that I would no longer have the luxury of adding subscribers through their API.

But, like any developer worth their salt, I was undeterred and ready to find an alternative. After meticulous research and consideration, I decided to go with Mailchimp. With its renowned reputation, a generous free tier, and well-documented APIs, Mailchimp seemed like the perfect fit.

Without missing a beat, I set out to create a new connector that would seamlessly link my application with Mailchimp. Fortunately, Mailchimp's connector relied on a basic auth header, a feature that integrated seamlessly with Saloon, right at the connector level.

public function resolveBaseUrl(): string
{
    return 'https://us8.api.mailchimp.com/3.0/';
}

protected function defaultHeaders(): array
{
    $mailChimpApiKey = config('services.mailchimp.api-key');

    return [
        'Authorization' => 'Basic '.base64_encode('anystring:'.$mailChimpApiKey),
    ];
}

As you can see, configuring the base URI and default headers in Saloon streamlined the entire connectivity process. The only remaining task was sending a POST request to Mailchimp's API to add a new contact. Since all the necessary data resided comfortably within my controller, the Saloon Request class simply had to transmit it. Here's a glimpse of my Saloon Request:

class MailChimpSubscribe extends Request implements HasBody
{
    use HasJsonBody;

    protected Method $method = Method::POST;

    public function __construct(
        protected array $payload
    ) {
    }

    public function defaultBody(): array
    {
        return $this->payload;
    }

    public function resolveEndpoint(): string
    {
        return '/lists/'.config('services.mailchimp.list-id').'/members';
    }
}

With that accomplished, my Controller code underwent a small transformation:

$data = [
    'email_address' => $input['email'],
    'status' => 'pending',
    'merge_fields' => [
        'MMERGE6' => $blog->category->name,
        'MMERGE7' => $tags,
        'MMERGE8' => $blog->title,
    ],
];

$mailChimpConnector = new MailChimpConnector();
$resp = $mailChimpConnector->send(new MailChimpSubscribe($data));

While the intricacies of how the fields were populated remain closely guarded implementation details, I can reveal that I did perform a thorough check to ensure the success of the request.

Conclusion

In conclusion, the journey from Beehiiv to Mailchimp, with Saloon as our trusty co-pilot, serves as a testament to the adaptability and power of modern development tools. The realm of API integration may be riddled with challenges, but armed with the right solutions, like Saloon, you're well-equipped to navigate these waters with confidence and ease. As developers, our ability to pivot, adapt, and find innovative solutions is what propels us forward in this ever-evolving tech landscape. So, as you embark on your own integration adventures, remember that the right tool can make all the difference, turning roadblocks into stepping stones on the path to success.

Happy coding!