Introducere în API REST cu Python

Ce este un API

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

REST (Representational State Transfer) este stilul cel mai des folosit pentru proiectarea unor astfel de API-uri. Nu este un protocol și nici o bibliotecă — este un set de reguli despre cum se construiesc URL-urile, metodele și răspunsurile. 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 bazează pe câteva principii:

Client–server — cele două părți sunt separate și evoluează separat.
Fără stare — fiecare cerere conține tot ce îi trebuie serverului; serverul nu reține nimic între cereri.
Interfață uniformă — aceleași URL-uri, metode și coduri de stare înseamnă peste tot același lucru.
Posibil de pus în cache — răspunsurile pot spune „poți refolosi acest răspuns”, economisind drumuri dus-întors.
Pe straturi — proxy-uri, gateway-uri și echilibratoare de sarcină pot sta între client și server fără ca vreunul dintre ei 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 stare + antete + corp). Iată un ciclu complet dus-întors în Python — demonstrația pornește un mic server local într-un fir de execuție în fundal, astfel încât programul poate rula și se poate încheia singur.

Un ciclu complet dus-întors

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

Un detaliu al demonstrației: handler-ul suprascrie log_message cu o metodă goală. Clasa de bază ar afișa câte o linie de jurnal cu marcaj de timp pentru fiecare cerere, iar demonstrația vrea exact ieșirea afișată — nimic altceva.

Scrie un program Python care arată un ciclu REST complet: pornește un mic http.server pe un port liber, într-un fir de execuție în fundal, al cărui handler răspunde la GET /users/1 cu un utilizator în format JSON și un antet Content-Type, trimite cererea cu urllib.request și afișează linia cererii, starea răspunsului, tipul de conținut și corpul.

> Ieșire: program Python complet

Prompt

Scrie un program Python care arată un ciclu REST complet: pornește un mic http.server pe un port liber, într-un fir de execuție în fundal, al cărui handler răspunde la GET /users/1 cu un utilizator în format JSON și un antet Content-Type, trimite cererea cu urllib.request și afișează linia cererii, starea răspunsului, tipul de conținut și corpul.

Ieșire: program Python complet

import threading
import urllib.request
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer

class Handler(BaseHTTPRequestHandler):
  def do_GET(self):
    self.send_response(200)
    self.send_header("Content-Type", "application/json")
    self.end_headers()
    self.wfile.write(b'{"id": 1, "name": "Ana"}')

  def log_message(self, fmt, *args):
    pass  # dezactivăm jurnalul de cereri încorporat, ca ieșirea să rămână curată

# Un server mic pentru demonstrație (unul real s-ar bloca în serve_forever).
server = ThreadingHTTPServer(("127.0.0.1", 0), Handler)
port = server.server_address[1]
threading.Thread(target=server.serve_forever, daemon=True).start()

with urllib.request.urlopen(f"http://127.0.0.1:{port}/users/1") as resp:
  print("cerere: GET /users/1")
  print("stare: ", resp.status, resp.reason)
  print("tip:   ", resp.headers["Content-Type"])
  print("corp:  ", resp.read().decode())

server.shutdown()

Metode, coduri de stare și limite

Metodele HTTP corespund celor patru operații cu date (CRUD):

GET citește o resursă · POST creează una · PUT înlocuiește una · PATCH modifică o parte din una · DELETE șterge una.

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

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