Working with APIs

Introduction

So far you have learned how to filter data, apply regex, and encode or decode JSON and XML — all skills you need to talk to the outside world. This lesson puts them together: making an outbound HTTP request from PHP to a REST API, and working with the response it sends back.

You will see two ways to do this — the simple file_get_contents() with a stream context, and the more capable cURL extension — plus how to safely decode and use the JSON response.

What Is a REST API?

A REST API is a web service that responds to HTTP requests — typically GET, POST, PUT, and DELETE — at specific URLs, and usually returns data as JSON. When your PHP script "calls an API," it is really just making an HTTP request to another server, exactly like a browser does, and reading the response body.

Making Requests with file_get_contents()

PHP's file_get_contents() can read from a URL just as easily as a local file, as long as the "allow_url_fopen" setting is enabled (it is by default on most setups). For a simple GET request, you can call it with nothing more than the URL.

<?php
$response = file_get_contents("https://jsonplaceholder.typicode.com/users/1");

if ($response === false) {
    echo "Request failed.";
} else {
    echo $response;
}

{"id":1,"name":"Leanne Graham","username":"Bret","email":"Sincere@april.biz", ...}

For more control — setting a timeout, custom headers, or a different HTTP method — wrap the request in a stream context using stream_context_create().

<?php
$options = [
    "http" => [
        "method"  => "GET",
        "header"  => "Accept: application/json\r\n",
        "timeout" => 5,
    ],
];

$context = stream_context_create($options);
$response = file_get_contents("https://jsonplaceholder.typicode.com/users/1", false, $context);

echo $response !== false ? "Request succeeded." : "Request failed.";

Request succeeded.

Making Requests with cURL

The cURL extension is more powerful and flexible than file_get_contents() — it gives you detailed control over headers, methods, timeouts, authentication, and error handling, and is the standard choice for anything beyond the simplest request.

<?php
$ch = curl_init("https://jsonplaceholder.typicode.com/users/1");

curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); // return the response instead of printing it
curl_setopt($ch, CURLOPT_TIMEOUT, 5);
curl_setopt($ch, CURLOPT_HTTPHEADER, ["Accept: application/json"]);

$response = curl_exec($ch);

if (curl_errno($ch)) {
    echo "cURL error: " . curl_error($ch);
} else {
    echo $response;
}

curl_close($ch);

{"id":1,"name":"Leanne Graham","username":"Bret","email":"Sincere@april.biz", ...}

The typical cURL pattern is always the same: curl_init() to start a session, curl_setopt() to configure it, curl_exec() to send the request, and curl_close() to clean up.

Decoding the JSON Response

Whichever method you use to fetch the response, the body usually arrives as a raw JSON string. Decode it with json_decode() (covered in an earlier lesson) before working with the data as normal PHP values.

<?php
$response = file_get_contents("https://jsonplaceholder.typicode.com/users/1");

$user = json_decode($response, true);

if (json_last_error() !== JSON_ERROR_NONE) {
    echo "Could not parse API response.";
} else {
    echo "Name: {$user['name']}\n";
    echo "Email: {$user['email']}";
}

Name: Leanne Graham
Email: Sincere@april.biz

Example: Fetching from a Public API

Here is a complete example using cURL to fetch a short list of posts from a free placeholder API and display just the fields we care about.

<?php
$ch = curl_init("https://jsonplaceholder.typicode.com/posts?_limit=3");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_TIMEOUT, 5);

$response = curl_exec($ch);

if (curl_errno($ch)) {
    echo "Request failed: " . curl_error($ch);
    curl_close($ch);
    exit;
}
curl_close($ch);

$posts = json_decode($response, true);

if (json_last_error() !== JSON_ERROR_NONE) {
    echo "Could not parse response.";
    exit;
}

foreach ($posts as $post) {
    echo "#{$post['id']}: {$post['title']}\n";
}

#1: sunt aut facere repellat provident occaecati excepturi optio reprehenderit
#2: qui est esse
#3: ea molestias quasi exercitationem repellat qui ipsa sit aut

Notice the pattern that will repeat across almost every API integration you write: make the request, check for a transport-level error, check for a JSON-decoding error, then use the resulting PHP array like any other data.

Common Mistakes

Best Practices

Frequently Asked Questions

Key Takeaways

Summary

Calling external APIs is one of the most practical things you will do as a PHP developer — nearly every real application talks to at least one third-party service. You now know how to make requests with both file_get_contents() and cURL, and how to safely decode and use the JSON they return.

With filtering, regex, JSON, XML, and API calls behind you, you are ready to move into working with databases, starting with an introduction to MySQL.