Configuring Base URLs in the Laravel HTTP Client

When Laravel code sends several requests to the same API, each request can include the API’s host and path prefix. Laravel’s HTTP client lets you set that shared address once with baseUrl(), then send requests using only the path that identifies each API resource or action. A base URL is the shared starting address for those requests.

This keeps repeated calls shorter and gives you one place to update the API address. You can also reuse the configured client with a macro, a named shortcut for common HTTP request settings.

Set the base URL for a request

Call baseUrl() on Laravel’s Http facade before choosing a request method:

use Illuminate\Support\Facades\Http;

$response = Http::baseUrl('https://api.example.com')
    ->get('/users');

Here, baseUrl() sets the starting address for the request, and get() sends a GET request to the users endpoint. Laravel documents this method and demonstrates setting a base URL before sending a request in its HTTP client documentation.

For repeated calls, define a macro that returns a client with the shared URL and other common settings, such as JSON headers or an access token:

use Illuminate\Support\Facades\Http;

Http::macro('partnerApi', function () {
    return Http::acceptJson()
        ->withToken(config('services.partner.token'))
        ->baseUrl(config('services.partner.base_url'));
});

// Use the configured client for an endpoint request:
$response = Http::partnerApi()->get('/users');

Register the macro where your code defines reusable HTTP configuration. Each call to Http::partnerApi() then starts with the same base URL and request settings. Laravel’s documentation uses this macro pattern to reuse headers and a base URL across requests.

Use endpoint paths after setting the base URL

An endpoint path is the part of an API address that identifies a resource or action. After setting a base URL, pass that path to the request method. For a base URL containing only the host, get('/users') sends a request to the users endpoint. This path avoids repeating the API host with every request.

If the base URL also contains a path prefix, such as an API version, use a consistent slash convention. For example:

Http::baseUrl('https://api.example.com/v1/')
    ->get('users');

Laravel News recommends a trailing slash on a path-prefixed base URL and endpoint paths without a leading slash for this pattern. The resulting URL is intended to include the /v1/ prefix before users.

Laravel’s documentation does not define every combination of leading and trailing slashes for all supported versions. If your API base URL includes a path prefix, verify the final request URL in your Laravel version. Laravel’s HTTP testing tools include an assertion for checking a sent request’s URL.

What I'm building

Delegate tasks. Get software.

Give Vroni a GitHub issue, bug report, spec, or rough idea. It reads the repo, plans the change, writes code, runs checks, and works toward a review-ready pull request.

Take a look at vroni.com