Connecting to external APIs is a common task in web development. APIs allow you to integrate data and functionality from other applications into your own app. In this tutorial, we’ll look at how to connect to APIs in Laravel, the popular PHP web framework.
Laravel provides easy ways to call APIs and work with the responses. We’ll cover making GET and POST requests to APIs, handling errors, and processing JSON and other response formats. By the end, you’ll know how to connect your Laravel app to any REST API.
Prerequisites
Before we dive in, you’ll need the following:
- Basic knowledge of PHP and Laravel
- Composer installed to manage Laravel dependencies
- An API to connect to – we’ll use a test JSONPlaceholder API, but the concepts apply to any web API
- Laravel project set up on your computer or development server
With those covered, let’s get started!
Sending GET Requests
The simplest type of API request is a GET request, which retrieves data from the API. Many APIs support GET requests to return data to your application.
In Laravel, you can make GET requests using the HTTP client fluent interface. Here’s an example:
“`php
use Illuminate\Support\Facades\Http;
$response = Http::get(‘https://jsonplaceholder.typicode.com/posts’);
“`
This makes a GET request to the JSONPlaceholder posts API and stores the response in the $response variable.
The get() method returns an Illuminate\Http\Client\Response instance with various methods to inspect the response:
“`php
$response->status(); // 200
$response->json(); // JSON response as array
“`
So with GET requests, it’s simple to call an API and get back JSON or other data.
Adding Query Parameters
To include query string parameters with the GET request, chain the query() method:
“`php
$response = Http::get(‘https://jsonplaceholder.typicode.com/posts’)
->query([‘userId’ => 1]);
“`
This appends ?userId=1 to the request URL. The API returns posts only for that user ID.
You can add multiple parameters by passing an associative array to the query() method.
Making POST Requests
Along with GET requests, APIs often allow POST requests to create new resources. For example, a POST request to the /posts endpoint may create a new blog post.
To make POST requests in Laravel, use the post() method:
“`php
$response = Http::post(‘https://jsonplaceholder.typicode.com/posts’, [
‘title’ => ‘New Post’,
‘body’ => ‘This is the post body’,
‘userId’ => 1,
]);
“`
The second argument contains an associative array of data to POST to the API. The API will create a new post resource using this data.
You can check the response status and access the returned JSON like with GET requests:
“`php
if ($response->status() === 201) {
// Successful creation
echo $response->json()[‘id’];
}
“`
This checks for a 201 Created status, indicating the post was created successfully. We can access the returned post ID using the json() method.
POST JSON Data
For APIs that accept JSON-encoded request bodies, you may find it cleaner to specify the POST data as a JSON string:
“`php
$data = [
‘title’ => ‘New Post’,
‘body’ => ‘This is the post body’,
‘userId’ => 1,
];
$response = Http::post(‘https://jsonplaceholder.typicode.com/posts’, $data);
“`
Laravel will encode the $data array to JSON automatically. This makes your request match APIs documented as accepting JSON request bodies.
File Uploads
To upload files via POST, use the attach() method:
“`php
Http::post(‘https://example.com/upload’, [
‘photo’ => Http::attach($pathToFile, ‘photo.jpg’),
]);
“`
This attaches the file as a “photo” form field in the POST data. The attach() method handles properly encoding the file data.
Handling API Errors
APIs can return non-success HTTP status codes like 400 Bad Request or 500 Internal Server Error. Laravel includes helpful methods to catch these errors.
One approach is try/catch blocks:
“`php
try {
$response = Http::post(‘https://example.com/posts’, $data);
} catch (Illuminate\Http\Client\RequestException $e) {
if ($e->response->status() === 422) {
// Handle validation errors
}
return back()->withErrors(‘Unable to create post’);
}
“`
We attempt the POST request in the try block. If an exception occurs, the catch block lets us check the failed response status and handle it.
Alternatively, you can use the throw() method to throw an exception if the status is non-200 level:
“`php
$response = Http::post(‘https://example.com/posts’, $data)->throw();
// API call was successful
“`
This will throw an HttpException you can catch. The exception includes the failed response instance.
Catching API errors allows your app to gracefully handle failed requests. The user gets a useful error message instead of a blank screen or 500 error.
Working with JSON APIs
Many modern APIs return responses formatted as JSON (JavaScript Object Notation). JSON is a lightweight data format that’s easy for platforms to parse.
Laravel includes features to simplify working with JSON APIs.
Convert Response to Array
To decode a JSON response into a PHP array or object, use the json() method:
“`php
$response = Http::get(‘https://jsonplaceholder.typicode.com/posts/1’);
$post = $response->json();
echo $post[‘title’]; // sunt aut facere
“`
The json() method decodes the response body JSON into an array. You can access properties directly on the array.
Return Collections from JSON
For APIs that return a JSON array, you may want to convert responses into Laravel collections. This allows using collection methods like map() and filter():
“`php
$posts = Http::get(‘https://jsonplaceholder.typicode.com/posts’)
->collect();
$postTitles = $posts->map(function ($post) {
return $post[‘title’];
});
“`
The collect() method converts the JSON array directly into a collection instance. We can then use collection methods like map() on the posts.
Convert Models from JSON
You can also convert JSON responses into instances of custom model classes.
First, make your model use the Illuminate\Http\Client\ResponseTrait trait:
“`php
use Illuminate\Http\Client\ResponseTrait;
class Post
{
use ResponseTrait;
// Class properties…
}
“`
Then call the toModel() method on the response:
“`php
$post = Http::get(‘https://jsonplaceholder.typicode.com/posts/1’)
->toModel(Post::class);
echo $post->title; // sunt aut facere
“`
The JSON automatically maps properties onto your Post model instance!
This provides an easy way to work with APIs that return data matching your Eloquent models.
Advanced Usage
Let’s look at some more advanced API client usage:
Customizing Requests
You can set custom headers, data, timeouts, and more on the request using methods:
“`php
$response = Http::withHeaders([
‘Authorization’ => ‘Bearer abc123’,
])->timeout(10)->retry(3, 100)
->post(‘https://example.com/users’, [
// …
]);
“`
See the HTTP client documentation for the available methods.
Base URIs
For APIs you call frequently, you can set a base URI. First get an instance:
“`php
// Assign base URI
$client = Http::baseUrl(‘https://example.com/api/’);
// Call endpoints without full URL
$response = $client->get(‘posts’);
“`
The client will prepend the base URL to all requests. This keeps code DRY instead of repeating the full API endpoint URL.
Testing and Faking
When testing code that makes API calls, you may want to fake or mock the responses.
Laravel’s HTTP client has a fake() helper that stubs responses:
“`php
Http::fake([
‘https://jsonplaceholder.typicode.com/*’ => Http::response([
‘post title’ => ‘Test Post’,
], 200, [‘Headers’]),
]);
$response = Http::get(‘https://jsonplaceholder.typicode.com/posts/1’);
// Returns mocked response
“`
For a request URL matching the pattern, it will return the faked response. The same syntax works for fake POST, PUT, DELETE requests.
This avoids hitting real APIs during tests or where you need sample hardcoded responses.
Wrapping Up
That covers the basics of connecting to APIs in Laravel! The key takeaways are:
- Use Laravel’s HTTP client fluent interface for requests
- GET and POST data easily with get() and post()
- Inspect response status codes and cast to JSON
- Catch request exceptions for error handling
- Integrate JSON responses into collections and models
The HTTP client handles many complexities, like JSON encoding, behind the scenes. With these basics you can integrate external data into your Laravel apps.
For next steps, review the full documentation and advanced usage guides as you build out your API features.
Frequently Asked Questions
What is an API?
API stands for Application Programming Interface. APIs allow different software systems to communicate with each other by calling endpoints exposed by the API. Web APIs typically transfer data using HTTP requests and return responses in a machine-readable format like JSON.
Is an API key required to call APIs?
Some APIs require an API key or access token to be included in requests. This identifies the caller and may be used to control access and track usage. The API documentation will provide instructions on how to obtain and pass an API key. Other APIs are completely open.
Can I connect to APIs without Laravel?
Yes, you can make API calls in pure PHP without using Laravel. The curl, stream_context_create, and file_get_contents functions can make HTTP requests. You would have to handle JSON encoding, error handling, and other logic yourself that Laravel’s HTTP client provides out of the box.
Is there a limit to how much data I can retrieve from an API?
Most APIs have some limits in place to prevent abuse. There may be limits on the number of API requests per day/hour or the number of results returned by a pagination query. Check the API documentation for specifics on rate limits. Some APIs require payment at higher usage tiers.
How can I cache API responses?
Caching avoids hitting the external API on every request. In Laravel, you can use the remember() method on the HTTP client to cache responses. You can also serialize responses and store them in Laravel’s cache or database for faster lookup. Develop a caching strategy that fits your API usage patterns.
Conclusion
Connecting Laravel applications to external web APIs opens up many possibilities for building useful features. Whether you’re accessing data, offloading processing, or adding functionality, the HTTP client and response handling tools make development straightforward.
As you work with more APIs, you’ll find common patterns like authentication, error handling, and JSON parsing emerge. Laravel’s request and response abstractions provide what you need for robust API integrations without added complexity in your application code.