Tutorial: Handling HTTP Requests and Raw Responses in Laravel

In Laravel, making HTTP requests is made easy with the Http facade, which provides a simple and fluent interface to interact with external APIs. In this tutorial, we will explore how to make POST requests, handle various types of responses, and process raw response bodies in a Laravel application.

Table of Contents

1. [Making a Basic POST Request](#making-a-basic-post-request)
2. [Sending a POST Request with API Key](#sending-a-post-request-with-api-key)
3. [Sending a POST Request with Bearer Token](#sending-a-post-request-with-bearer-token)
4. [Handling JSON Responses](#handling-json-responses)
5. [Handling Raw Responses](#handling-raw-responses)
6. [Parsing Query Parameters in Responses](#parsing-query-parameters-in-responses)
7. [Error Handling and Additional Considerations](#error-handling-and-additional-considerations)

Prerequisites

Ensure you have a Laravel project set up. You can create a new Laravel project by running:

composer create-project --prefer-dist laravel/laravel example-app

Make sure to have php and composer installed on your machine.

1. Making a Basic POST Request

Laravel's Http facade simplifies making POST requests to external APIs. Here’s how you can send a basic POST request with some data:

use Illuminate\Support\Facades\Http;

$response = Http::post('https://api.example.com/endpoint', [
    'key1' => 'value1',
    'key2' => 'value2',
]);

dd($response->body()); // Display the raw response body

Explanation:

• Http::post(): This sends a POST request to the specified URL.
• $response->body(): Returns the raw response body, which can be used as needed.

2. Sending a POST Request with API Key

Some APIs require an API key for authentication. You can pass headers using Laravel’s Http facade easily.

use Illuminate\Support\Facades\Http;

$response = Http::withHeaders([
    'Api-Key' => 'your-api-key',
])->post('https://api.example.com/endpoint', [
    'key1' => 'value1',
    'key2' => 'value2',
]);

dd($response->body());

Explanation:

• Http::withHeaders(): Adds custom headers, such as an API key, to the request.

3. Sending a POST Request with Bearer Token

When working with OAuth or JWT-based APIs, you may need to pass a Bearer Token for authentication.

use Illuminate\Support\Facades\Http;

$response = Http::withToken('your-bearer-token')->post('https://api.example.com/endpoint', [
    'key1' => 'value1',
    'key2' => 'value2',
]);

dd($response->body());

Explanation:

• Http::withToken(): Adds a Bearer Token for authorization in the request headers.

4. Handling JSON Responses

Most modern APIs return data in JSON format. Laravel simplifies handling JSON responses by providing a json() method.

use Illuminate\Support\Facades.Http;

$response = Http::post('https://api.example.com/endpoint', [
    'key1' => 'value1',
    'key2' => 'value2',
]);

$data = $response->json(); // Automatically parses JSON response into an associative array
dd($data);

Explanation:

• $response->json(): Decodes the JSON response to an associative array automatically, allowing you to work with it directly in PHP.

5. Handling Raw Responses

Sometimes, you might receive raw responses in formats other than JSON, such as a query string or plain text. Here’s how to handle and process raw responses:

use Illuminate\Support\Facades\Http;

$response = Http::post('https://api.example.com/endpoint', [
    'key1' => 'value1',
    'key2' => 'value2',
]);

$rawResponse = $response->body(); // Get the raw response as a string
dd($rawResponse);

Explanation:

• $response->body(): This retrieves the raw response body as a string, which you can then process based on its format.

6. Parsing Query Parameters in Responses

If the raw response is in the form of a query string (e.g., key1=value1&key2=value2), you can use PHP’s built-in parse_str() function to convert it into an associative array.

use Illuminate\Support\Facades\Http;

$response = Http::post('https://api.example.com/endpoint', [
    'key1' => 'value1',
    'key2' => 'value2',
]);

$rawResponse = $response->body(); // Get the raw response
$parsedResponse = [];

// Parse the query string into an associative array
parse_str($rawResponse, $parsedResponse);

dd($parsedResponse); // Now you can work with the associative array

Explanation:

• parse_str(): Parses the query string into an associative array. This is useful when working with URL-encoded responses.

7. Error Handling and Additional Considerations

It’s important to handle errors gracefully in production. Laravel’s Http facade offers methods to check if a request was successful.

use Illuminate\Support\Facades\Http;

$response = Http::post('https://api.example.com/endpoint', [
    'key1' => 'value1',
    'key2' => 'value2',
]);

if ($response->successful()) {
    dd($response->json()); // Handle successful response
} elseif ($response->failed()) {
    dd('Request failed: ' . $response->body()); // Handle failed request
}

Explanation:

• $response->successful(): Returns true if the response has a status code of 200-299.
• $response->failed(): Returns true if the request failed (status code of 400 or greater).

Other useful methods include:

• $response->status(): Returns the HTTP status code.
• $response->header('header-name'): Retrieves a specific response header.

Conclusion

In this tutorial, we covered how to handle various HTTP requests in Laravel using the Http facade, including:

1. Sending basic POST requests.
2. Adding headers such as API keys and Bearer Tokens.
3. Handling JSON and raw responses.
4. Parsing query string parameters.
5. Error handling for production readiness.

Laravel’s Http facade provides a simple yet powerful way to work with APIs, making HTTP requests and handling responses intuitive and clean. By utilizing the methods discussed, you can seamlessly integrate external services into your Laravel application.