Introducere în API REST cu Go

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 nici protocol, nici bibliotecă — este un set de reguli despre cum se formează adresele URL, 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 propria adresă 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 adrese URL, metode și coduri de stare înseamnă peste tot același lucru.
Poate fi 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 î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 stare + antete + corp). Iată un ciclu complet în Go — demonstrația pornește un server de test minuscul, ca programul 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 program Go care arată un ciclu REST complet: pornește un server httptest al cărui handler răspunde cu un utilizator în format JSON și cu un antet Content-Type, trimite o cerere GET către /users/1 și afișează linia cererii, statusul răspunsului, tipul conținutului și corpul.

> Ieșire: program Go și rezultatul capturat

Prompt

Scrie un program Go care arată un ciclu REST complet: pornește un server httptest al cărui handler răspunde cu un utilizator în format JSON și cu un antet Content-Type, trimite o cerere GET către /users/1 și afișează linia cererii, statusul răspunsului, tipul conținutului și corpul.

Ieșire: program Go și rezultatul capturat

package main

import (
  "fmt"
  "io"
  "net/http"
  "net/http/httptest"
)

func main() {
  // Un server mic pentru demonstrație (unul real ar folosi ListenAndServe).
  server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
    w.Header().Set("Content-Type", "application/json")
    fmt.Fprint(w, `{"id": 1, "name": "Ana"}`)
  }))
  defer server.Close()

  resp, err := http.Get(server.URL + "/users/1")
  if err != nil {
    fmt.Println("cererea a eșuat:", err)
    return
  }
  defer resp.Body.Close()
  body, _ := io.ReadAll(resp.Body)

  fmt.Println("cerere:  GET /users/1")
  fmt.Println("status: ", resp.Status)
  fmt.Println("tip:    ", resp.Header.Get("Content-Type"))
  fmt.Println("corp:   ", string(body))
}

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 schimbă o parte din ea · DELETE o șterge.

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 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 ști limitele face parte din a cunoaște stilul.