Introducere în API REST cu TypeScript

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 să dai formă adreselor URL, 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 propria adresă URL, precum /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 reține nimic între cereri.
Interfață uniformă — aceleași adrese URL, metode și coduri de status înseamnă același lucru peste tot.
Cacheabil — răspunsurile pot spune „poți refolosi acest răspuns”, economisind drumuri dus-întors.
În 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

Fiecare 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 TypeScript — demonstrația pornește un mic server local, astfel încât programul să poată rula și să se termine 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 program TypeScript care arată un ciclu REST complet: pornește un mic server local node:http pe portul 0, al cărui handler răspunde cu un utilizator în format JSON și un antet Content-Type, trimite o cerere GET către /users/1 cu fetch, afișează linia cererii, statusul răspunsului, tipul de conținut și corpul, apoi închide serverul.

> Ieșire: program TypeScript și rezultatul capturat

Prompt

Scrie un program TypeScript care arată un ciclu REST complet: pornește un mic server local node:http pe portul 0, al cărui handler răspunde cu un utilizator în format JSON și un antet Content-Type, trimite o cerere GET către /users/1 cu fetch, afișează linia cererii, statusul răspunsului, tipul de conținut și corpul, apoi închide serverul.

Ieșire: program TypeScript și rezultatul capturat

import { createServer } from "node:http"

async function main(): Promise<void> {
  // Un mic server local pentru demonstrație. Portul 0 înseamnă „orice port liber”,
  // așa că exemplul nu intră niciodată în conflict cu ceva deja pornit.
  const server = createServer((req, res) => {
    res.writeHead(200, { "Content-Type": "application/json" })
    res.end('{"id": 1, "name": "Ana"}')
  })
  await new Promise<void>(resolve => server.listen(0, () => resolve()))
  const port = (server.address() as { port: number }).port

  const res = await fetch(`http://localhost:${port}/users/1`)
  const body = await res.text()

  console.log("cerere: GET /users/1")
  console.log("status: ", res.status, res.statusText)
  console.log("tip:    ", res.headers.get("content-type"))
  console.log("corp:   ", body)

  server.close()
}

main()

Metode, coduri de status ș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 status 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 sincere: 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.