Laravel: Tiding up your API requests

Nobody wants a wall of text of method only to push a tweet

Photo by Taylor Vick on Unsplash

Twitter new ruler has shot down free usage of their API, and some folks have decided to refactor their application to use other social networks. It’s not like anyone wants to pay a dollar for 3 requests, but here we are now.

The problem with that refactoring are HTTP Server Requests. There can be so many, in so many places, that is quite a job to update them all. If you didn’t centralized everything, you’re pretty much wasting a couple of days refactoring each request:

use Illuminate\Support\Facades\Http;

Http::baseUrl('https://www.social-network.org/api/v1')
    ->withToken(config('services.social-network.secret'))
    ->withHeaders(['X-Followers-Only' => 'true'])
    ->timeout(5)
    ->post('new', ['message' => 'This is tiresome']);

// Now do that again...

That’s why I decided to take that matter into my own hands, and create a package to centralize your API Servers and all their requests once for all. Well, nothing else I can do when The Taylor shoot down my PR to include it on Laravel, but he has a point.

Well, here is a new concept.

An API Manager to manage your APIs

There are two problems when you start to make too much HTTP Server Requests to the Internet from your app:

1. Having to configure each request, multiple times, for each different destination, across your application.
2. Having multiple endpoints for a single server, each with their own set of attributes and arguments.

The Laragear API Manager solves both problems by letting you simplify each HTTP Server configuration with a single class, all reachable within themselves, and having multiple methods to customize (and even chain) each request to be sent. Is just a Composer call away.

composer require laragear/api-manager

For example, let’s hypothetically have access to the Chirper API. Instead of sending a mail in hopes they make an SDK for PHP and wait, we can make our own with a simple command.

php artisan make:api Chirper

An API Server is just a class with some global configuration. It even comes with a method to set up proper authentication.

namespace App\Http\Apis;

use Laragear\ApiManager\ApiServer;

class Chirper extends ApiServer
{
    public function getBaseUrl()
    {
        return 'https://chirper.com/api/v1';
    }

    public function authToken()
    {
        return config('services.chirper.secret');
    }
}

The next step to solve with API Servers are the multitude of endpoints. We can solve it with “actions”. Actions can be a simple array of routes by name, but also the classic class method for more complex customization.

class Chirper extends ApiServer
{
    // ...

    public array $actions = [
        'chirp'  => 'post:/new',
        'edit'   => 'patch:/chirp/{chirp}',
        'delete' => 'delete:/chirp/{chirp}',
    ];

    public function onlyForFollowers(PendingRequest $request)
    {
        $request->withHeaders(['X-Followers-Only' => 'true']);

        return $this;
    }

    public function quoting(PendingRequest $request, $id)
    {
        $request->withHeaders(['X-Quote' => $id]);
     
        return $this;
    }
}

The magic behind the API Server call is not the class itself, but a proxy which sits in front. Each method call, or even property access, is routed to the API Server you created, or the PendingRequest instance you’re familiar with.

To use any of your defined API Servers, just call api() on them and create a request to send.

use App\Http\Apis\Chirper;

Chirper::api()->timeout(5)->onlyForFollowers->quoting(293158223)->chirp([
    'message' => 'This kind of chirps is what makes Chirper awesome!'
]);

To send concurrent requests, you only need to use the on() method which is god send when you need to replicate the same data across multiple services.

use Illuminate\Support\Facades\Http;
use App\Http\Apis\Chirper;
use App\Http\Apis\Twitter;
use App\Http\Apis\Facebook;
use App\Http\Apis\Mastodon;

Http::pool(fn ($pool) => [
    Chirper::api()->on($pool)->chirp($message),
    Twitter::api()->on($pool)->tweet($message),
    Facebook::api()->on($pool)->post($message),
    Mastodon::api()->on($pool)->say($message),
]);

If you’re tired of managing multiple API Servers in your application, you may want to try out the Laragear API Manager package, which is compatible with Laravel 10 and Laravel 9 if you didn’t upgrade already.

GitHub - Laragear/ApiManager: Manage multiple REST servers to make requests in few lines and…