Introducere în API REST cu PHP

Ce este un API

Un API (Application Programming Interface) este un contract care permite unui program să comunice cu altul. Un API web vorbește HTTP: un client trimite o cerere, serverul trimite înapoi un răspuns — de obicei purtând date JSON.

REST (Representational State Transfer) este cel mai răspândit stil de proiectare a unor astfel de API-uri. Nu este un protocol și nici o bibliotecă — este un set de reguli despre cum se dau forma URL-urilor, metodelor și răspunsurilor. HTTP transferă datele; REST spune cum să le organizezi.

Ideea centrală este resursa: fiecare lucru pe care îl gestionează API-ul tău — un utilizator, o comandă, o fotografie — are propriul URL, de exemplu /users/7.

Regulile REST

REST se sprijină pe câteva principii:

Client–server — cele două părți sunt separate și evoluează separat.
Fără stare — fiecare cerere poartă tot ce îi trebuie serverului; serverul nu ține minte nimic între cereri.
Interfață uniformă — aceleași URL-uri, metode și coduri de status înseamnă aceleași lucruri oriunde.
Cacheabil — răspunsurile pot spune „poți refolosi acest răspuns”, economisind drumuri dus-întors.
Pe straturi — proxy-uri, gateway-uri și echilibratoare de încărcare pot sta între client și server fără ca vreunul să observe.

O cerere, un răspuns

Orice interacțiune cu un API este acest ciclu: pleacă o cerere (metodă + URL + corp opțional) și se întoarce un răspuns (cod de status + antete + corp). Iată un ciclu complet în PHP — demonstrația scrie un mic script handler, pornește în fundal serverul web încorporat din PHP cu el și îl oprește la final, astfel încât scriptul să poată rula și să se încheie singur.

Un ciclu complet

Clientul cere GET /users/1; serverul răspunde cu statusul 200 OK, un tip de conținut și un corp JSON. Fiecare pagină din acest grup se construiește pe acest ciclu.

Scrie un script PHP care arată un ciclu REST complet: creează un script handler care răspunde cu un utilizator în format JSON și un antet Content-Type, pornește serverul web încorporat din PHP pe un port liber cu acest script, trimite o cerere GET către /users/1, afișează linia cererii, statusul răspunsului, tipul de conținut și corpul, apoi oprește serverul.

> Ieșire: script PHP

Prompt

Scrie un script PHP care arată un ciclu REST complet: creează un script handler care răspunde cu un utilizator în format JSON și un antet Content-Type, pornește serverul web încorporat din PHP pe un port liber cu acest script, trimite o cerere GET către /users/1, afișează linia cererii, statusul răspunsului, tipul de conținut și corpul, apoi oprește serverul.

Ieșire: script PHP

<?php

// Scriptul handler: serverul web rulează acest fișier o dată pentru fiecare cerere.
$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);

// Un port liber, apoi serverul web încorporat din PHP ca proces-copil.
$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);

// Un ciclu cerere-răspuns complet.
$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 "cerere: GET /users/1\n";
echo "status: $status\n";
echo "tip:    $type\n";
echo "corp:   $body\n";

proc_terminate($server);
proc_close($server);
unlink($routerFile);

Metode, coduri de status și limite

Metodele HTTP se pun în corespondență cu cele patru operații pe date (CRUD):

GET citește o resursă · POST creează una · PUT înlocuiește una · PATCH schimbă o parte din ea · DELETE o elimină.

Codurile de status spun cum a ieșit: 200 OK, 201 Created, 204 No Content, 400 Bad Request, 401 Unauthorized, 404 Not Found, 500 Internal Server Error.

Iar REST are limite recunoscute: nu este făcut pentru fluxuri în timp real, un răspuns poate purta mai mult sau mai puțin decât a vrut clientul, iar versionarea unui API public cere disciplină. A cunoaște limitele face parte din a cunoaște stilul.