Consuming APIs using Guzzle in Laravel (Article abandoned due to changes in Laravel)

Guzzle vs PHP’s built-ins

PHP has built-in support for cURL and HTTP requests, and these tools are perfectly valid for handling simpler requests.

Guzzle lets you get straight into developing your app.

Guzzle is a convenient helper for doing non-trivial work with APIs, and requests in general. It takes care of the code that you would have to write, test, and maintain. Guzzle lets you get straight into developing your app.

Integrating Guzzle with Laravel

Guzzle doesn’t have to be added as any kind of special middleware or Laravel-specific package. The standard way to integrate Guzzle is to use it “as is” via composer.

Firstly, install Guzzle via composer in your Laravel project folder.

composer require guzzlehttp/guzzle

Guzzle is now ready to be used in your Laravel project - Composer’s autoloader will make Guzzle available to your php files.

app/Http/Controllers/<<Name>>Controller.php

namespace App\Http\Controllers;
use Illuminate\Http\Request;

// add guzzle after the namespace 
use GuzzleHttp\Client;

class GuzzleController extends Controller
{

    public function index()
    {
        // instantiate a Guzzle client
        $client = new Client();
    }
}

Your first request

::: tip Note I will be consuming a publicly available API of TV shows from tvmaze.com.

The site doesn’t need authentication so it makes it easy to test the basics. :::

Guzzle handles typical REST verbs, these include the GET, POST, PUT, PATCH, and DELETE requests.

GET - retrieve data

Let’s start with GET request:

// search for the television sitcom 'Friends'
$response = $client->request('GET', 'https://api.tvmaze.com/search/shows?q=friends');

Shorten the request name

$client->get( is equivalent to $client->request('GET' as demonstrated below.

// same but shorter
$response = $client->get('https://api.tvmaze.com/search/shows?q=friends');

Set the base URI

If the API’s URL is https://api.tvmaze.com/search/shows?q=friends, set the base URI to https://api.tvmaze.com as show below.

$client = new GuzzleHttp\Client(['base_uri' => 'https://api.tvmaze.com/']);

Now you only need to type out the endpoint for each request instead of the whole URL.

// shorter, and less error prone
$response = $client->get('/search/shows?q=friends');

Advantages of using a base URI

• Typo errors: no more accidentally typing “wxample.com” when you meant “example.com”

• Keystrokes: stop typing the domain name over and over for each request

• Deployment: able to change the URI from dev to production with one variable

• Testability: easier to mock the endpoint by changing the base URI

• Maintainability: The root domain of endpoints will be loosely-coupled, becoming easy to change in future
  
  

Authentication (optional)

Your authentication method will vary between API providers.

Some of the most common methods are:

• Bearer token: Token is sent in the header as 'Authorization: Bearer abcd1234'

• Query string token: Supply the token in the query string e.g. https://example.com?access_token=abcd1234

• Basic HTTP authentication: provide your username and password
  
  

Authentication examples

// normally only need to use ONE of the auths below
$response = $client->get(
    '/search/shows?q=friends',
    [
        // bearer token example
        'headers' => [
            'Authorization' => 'Bearer abcd1234'
        ]
    
        // query string token example
        'query' => [
            'access_token' => 'abcd1234'
        ],
    
        // basic http authentication example
        'auth' => [
            'username', 'abcd1234'
        ]
    ]
);

Creating and changing data

POST - create a resource

PUT - replace a resource

PATCH - update part of a resource

DELETE - remove a resource

File uploads