Saloon - Package / SDK API integrations

As a proof of concept, we took the API of Tourism Flanders. This API has 400+ publicly accessible endpoints where you have different types of data such as: Flemish Lodges, City Tours, ...

The API that will be talked about in this example is the API of Flemish City Lodgings.

We'll start at the DemoSaloonSdk.php file. This is the central file of your SDK. Here the basic parameters like the base_url are filled in. This will also serve as the connector for your requests which will have to do with the Tourism Flanders API.

The first thing to do is use the trait/plugin AcceptsJson. This is a plugin provided by Saloon which ensures that you always send a JSON header on this connector.

After this, we fill in our baseUrl. In this case it is

https://opendata.visitflanders.org

If we look a little further we see that there is a $requests array. What we can do here is define our collections so that we can call them afterwards via a magic method and execute our request.

We will call our magic method lodgings and hang the LodgingsCollection on it as follows:

1
2
3
4
5
6
7
8
9
    /**
     * The requests/services on the DemoSaloonSdk.
     *
     * @var array
     * @method LodgingsCollection lodgings
     */
    protected array $requests = [
        'lodgings' => LodgingsCollection::class,
    ];

Everything else in the file is actually configured by default. Should you want to add a defaultConfig or defaultHeaders you can do so at the bottom of the file.

Now that our connector is set up, we need to create the collection we entered in $requests. Since that there is only 1 endpoint on the lodgings API we choose to create a function all() in the file. Because this is going to retrieve everything from the API.

If you go into the Requests folder you will see that there is an ExampleCollection.php present. We rename it to LodgingsCollection.php.

If we then create the agreed all() function and send the necessary query parameters to it so we can use it in the request then we can start building the request.

1
2
3
4
5
6
7
8
9
10
11
 /**
     * @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();
    }

First of all, we rename the Example folder in Requests to Lodgings. In Lodgings, we also suddenly rename the request that we are going to use to GetLodgingsRequest.php.

In the request file we are going to build the entire request. Think of it a bit like building the body.

In our construct we pass in the necessary values that we passed in the collection:

1
2
3
4
5
6
7
8
9
10
11
12
13
    /**
     * 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 define our endpoint:

/sector/accommodation/base_registry.json

We also add our query parameters:

1
2
3
4
5
6
7
8
public function defaultQuery(): array
    {
        return [
            'city' => $this->city,
            'limit' => $this->limit,
            'page' => $this->page
        ];
    }

and then we are done with the request!

Now we have a basic collection in which we can call a request in our Laravel/PHP application.

Now you can see that you can pack an API in a relatively quick way that you might be able to use in upcoming projects! Saloon opens up a lot of possibilities for both open-source and closed-source and thus can effectively make the DX a lot more enjoyable and increase work speed a lot afterwards.