What Is an API
An API (Application Programming Interface) is a contract that lets one program talk to another. A web API speaks HTTP: a client sends a request, the server sends back a response — usually carrying JSON data.
REST (Representational State Transfer) is the most common style for designing such APIs. It is not a protocol or a library — it is a set of rules for how to shape the URLs, methods and responses. HTTP transfers the data; REST says how to organize it.
The central idea is the resource: every thing your API manages — a user, an order, a photo — has its own URL, like /users/7.
The Rules of REST
REST rests on a few principles:
Client–server — the two sides are separate and evolve separately.
Stateless — every request carries everything the server needs; the server remembers nothing between requests.
Uniform interface — the same URLs, methods and status codes mean the same things everywhere.
Cacheable — responses can say "you may reuse this answer", saving round trips.
Layered — proxies, gateways and load balancers can sit between client and server without either noticing.
One Request, One Response
Every API interaction is this cycle: a request (method + URL + optional body) goes out, a response (status code + headers + body) comes back. Here is one full round trip in PHP — the demo writes a tiny handler script, starts PHP's built-in web server with it in the background, and stops it at the end, so the script can run and finish on its own.
A full round trip
The client asks GET /users/1; the server answers with status 200 OK, a content type, and a JSON body. Every page in this group builds on this cycle.
Output: PHP script
<?php
// The handler script: the web server runs this file once per request.
$router = <<<'PHP'
<?php
header("Content-Type: application/json");
echo '{"id": 1, "name": "Ana"}';
PHP;
$routerFile = sys_get_temp_dir() . "/pc-first-request.php";
file_put_contents($routerFile, $router);
// A free port, then PHP's built-in web server as a child process.
$probe = stream_socket_server("tcp://127.0.0.1:0");
$port = (int) explode(":", stream_socket_get_name($probe, false))[1];
fclose($probe);
$server = proc_open(["php", "-S", "127.0.0.1:$port", $routerFile],
[1 => ["file", "/dev/null", "w"], 2 => ["file", "/dev/null", "w"]], $pipes);
do {
usleep(20000);
$up = @fsockopen("127.0.0.1", $port);
} while ($up === false);
fclose($up);
// One full round trip.
$context = stream_context_create(["http" => ["ignore_errors" => true]]);
$body = file_get_contents("http://127.0.0.1:$port/users/1", false, $context);
[, $status] = explode(" ", $http_response_header[0], 2);
$type = "";
foreach ($http_response_header as $headerLine) {
if (stripos($headerLine, "Content-Type:") === 0) {
$type = trim(substr($headerLine, 13));
}
}
echo "request: GET /users/1\n";
echo "status: $status\n";
echo "type: $type\n";
echo "body: $body\n";
proc_terminate($server);
proc_close($server);
unlink($routerFile);
Methods, Status Codes and Limits
The HTTP methods map onto the four data operations (CRUD):
GET read a resource · POST create one · PUT replace one · PATCH change part of one · DELETE remove one.
Status codes tell how it went: 200 OK, 201 Created, 204 No Content, 400 Bad Request, 401 Unauthorized, 404 Not Found, 500 Internal Server Error.
And REST has honest limits: it is not built for real-time streams, a response may carry more or less than the client wanted, and versioning a public API takes discipline. Knowing the limits is part of knowing the style.