Saloon - Package / SDK API integrations

Als proof of concept hebben we de API van Toerisme Vlaanderen genomen. Deze API heeft 400+ publiek toegankelijke endpoints waar je verschillende soorten data hebt zoals: Vlaamse Logies, Stadsrondleidingen, ...

De API waar in dit voorbeeld over gesproken zal worden is de API van Vlaamse stadslogies.

We beginnen bij de DemoSaloonSdk.php file. Dit is de centrale file van je SDK. Hier worden de basis parameters ingevuld zoals de base_url. Deze gaat ook als connector dienen voor jouw requests die te maken zullen hebben met de Toerisme Vlaanderen API.

Wat we als eerste doen bij deze API is de trait/plugin AcceptsJson usen. Dit is een plugin die voorzien is door Saloon die er voor zorgt dat je op deze connector altijd een JSON header mee stuurt.

Hierna vullen we onze baseUrl in. In dit geval is dat

https://opendata.visitflanders.org

Als we wat verder kijken zien we dat er een $requests array is. Wat we hieron kunnen doen is onze collecties definiëren zodat we deze achteraf via een magic method kunnen oproepen en onze request kunnen uitvoeren.

Onze magic method gaan we lodgings noemen en hier hangen we dan de LodgingsCollection aan als volgt:

    /**
     * The requests/services on the DemoSaloonSdk.
     *
     * @var array
     * @method LodgingsCollection lodgings
     */
    protected array $requests = [
        'lodgings' => LodgingsCollection::class,
    ];

Voor de rest in de file is alles eigenlijk standaard geconfigureerd. Mocht je een defaultConfig willen toevoegen of defaultHeaders kan dat onderaan in de file.

Nu onze connector is opgezet, moeten we de collectie opmaken die we in $requests hebben ingevoerd. Aangezien dat er maar 1 endpoint is op de logies API kiezen we ervoor om in de file een functie te maken all(). Omdat deze alles gaat ophalen van de API.

Als je in de Requests map gaat zien zal je zien dat er een ExampleCollection.php aanwezig is. We gaan deze renamen deze naar LodgingsCollection.php.

Als wer hierin dan de afgesproken all() functie maken en de nodige query parameters aan mee sturen zodat we deze kunnen gebruiken in de request dan kunnen we de request beginnen opbouwen.

 /**
     * @throws ReflectionException
     * @throws GuzzleException
     * @throws SaloonException
     */

    public function all(?string $city = null, int $limit = -1, int $page = -1) : array
    {
        $request = $this->connector->request(new GetLodgingsRequest($city, $limit, $page));
        return $request->send()->json();
    }

Eerst en vooral renamen we de Example folder in Requests naar Lodgings. In Lodgings renamen we ook ineens de request dat we gaan gebruiken naar GetLodgingsRequest.php.

In de request file gaan we de volledige request opbouwen. Zie het een beetje als de body samenstellen.

In onze construct geven we de nodige waardes mee die we hebben meegegeven in de collectie:

    /**
     * Define constructor.
     *
     * @param string|null $city City you'd like to request lodgings from, leaving it empty will return all lodgings from Flanders.
     * @param int $limit Amount per page in pagination. -1 is the default (unlimited).
     * @param int $page current page in pagination. -1 is the default (disable pagination).
     */
    public function __construct(protected ?string $city, protected int $limit, protected int $page)
    {
        $this->city = $city;
        $this->limit = $limit;
        $this->page = $page;
    }

We definen ons endpoint:

/sector/accommodation/base_registry.json

Onze query parameters voegen we ook nog toe:

public function defaultQuery(): array
    {
        return [
            'city' => $this->city,
            'limit' => $this->limit,
            'page' => $this->page
        ];
    }

en dan zijn we klaar met de request!

Nu hebben we een basis collection waar we een request in kunnen aanroepen in onze Laravel/PHP applicatie.

Nu kan je zien dat je op een relatief snelle manier een API kan packagen die je misschien in volgende projecten ook nog kan gebruiken! Saloon opent heel wat mogelijkheden voor zowel open-source als closed-source en kan er dus effectief voor zorgen dat de DX heel wat aangenamer wordt en de werksnelheid heel wat verhoogd achteraf.