A REST API

1Mi az a HTTP?

A HTTP (HyperText Transfer Protocol) az a „nyelv”, amelyen a kliens és a szerver beszél. Két alapszabálya van:

• Kérés–válasz párokban működik. A kliens kérdez, a szerver válaszol. A szerver magától nem szólal meg. (Erre való a WebSocket vagy az SSE — de az nem HTTP-kérés.)
• Állapotmentes (stateless). Minden kérés önmagában áll: a szerver alapból nem emlékszik arra, mi volt az előző kérésben. Ha tudnia kell, ki vagy, azt minden kérésben el kell küldeni (például egy tokent).

A HTTP verziói: HTTP/1.1 (a legelterjedtebb, szöveges), HTTP/2 (bináris, párhuzamos), HTTP/3 (QUIC protokollon). A mi szempontunkból mindegyik ugyanúgy néz ki: kérés, válasz, metódus, státuszkód, fejlécek, törzs.

2Az URL felépítése

3A kérés és a válasz anatómiája

Mindkettő négy részből áll: kezdősor · fejlécek · üres sor · törzs.

Gyakori kérés-fejlécek

4HTTP-metódusok

A metódus azt mondja meg, mit akarunk tenni az erőforrással. Ugyanaz az URL egészen mást jelent attól függően, melyik metódussal hívjuk meg — nézzük végig őket egyesével.

GET — kérd le!

A leggyakoribb metódus: adatot kérünk, de nem változtatunk semmit. Ez az egyetlen, amit a böngésző címsorába beírva is ki tudsz próbálni, és ezt használja a böngésző minden képhez, CSS-fájlhoz, oldalhoz. Nincs törzse: amit közölni akarsz vele (szűrés, lapozás), az az URL query részébe kerül. Mivel nem változtat, a válasza nyugodtan gyorsítótárazható.

POST — hozz létre újat!

Új erőforrás létrehozására való: új termék, új rendelés, új felhasználó. Az adatot a kérés törzsében küldjük, JSON-ban. A szerver dönti el, milyen azonosítót kap az új elem — ezért a válaszban kapjuk vissza. Ha kétszer küldöd el, két dolog jön létre: ez a metódus nem ismételhető büntetlenül. (Ezen kívül a POST a „gyűjtőhely” minden olyan műveletnek, ami nem fér bele a CRUD-ba — például a bejelentkezés.)

PUT — cseréld le az egészet!

Egy létező erőforrás teljes felülírása. Fontos: a PUT-nál az erőforrás minden mezőjét el kell küldeni, mert amit kihagysz, az elveszik — a szerver a beküldött állapotra cseréli a régit. Ha ötször küldöd el ugyanazt, ötször ugyanaz lesz az eredmény, ezért idempotens.

PATCH — módosíts egy részletet!

Akkor használjuk, ha csak néhány mezőt akarunk megváltoztatni. Ha egy termék árát kell átírni, PATCH-csel elég ennyit küldeni: { "price": 29990 } — a név, a leírás és a kategória érintetlen marad. PUT-tal ugyanezért az egész terméket újra be kellene küldeni.

DELETE — töröld!

Az erőforrás törlése. Általában nincs törzse (minden információ benne van az URL-ben), és sikeres törlés után jellemzően nincs mit visszaadni. Idempotens: ha másodszor is elküldöd, a termék ugyanúgy nem lesz meg — az állapot tehát ugyanaz marad, még ha a második kérés 404-et is kap.

HEAD — csak a fejléceket kérem!

Pontosan ugyanaz, mint a GET, de a szerver csak a fejléceket küldi vissza, a törzset nem. Arra jó, hogy valamit megtudj az erőforrásról anélkül, hogy letöltenéd: létezik-e egyáltalán, mekkora (Content-Length), mikor változott utoljára. Például egy letöltőprogram ezzel nézi meg egy 2 GB-os fájl méretét, mielőtt nekikezdene.

OPTIONS — mit tudsz, végpont?

Azt kérdezi meg, milyen metódusokat fogad el az adott útvonal; a válasz egy Allow fejlécben sorolja fel őket. A gyakorlatban ritkán írod le kézzel — viszont a böngésző magától küldi az ún. előkérésekben (preflight), amikor egy oldal más eredetű API-t hív. Ha a hálózati fülön furcsa OPTIONS-kéréseket látsz a saját kérésed előtt, az a CORS működése.

Összefoglaló táblázat

* A PATCH lehet idempotens, ha jól tervezzük, de a szabvány nem garantálja.

Két fontos fogalom

Biztonságos (safe): a kérés nem változtat a szerver állapotán. A GET csak olvas.

Idempotens: ha ugyanazt a kérést többször elküldöd, az eredmény ugyanaz, mintha egyszer küldted volna.

5Státuszkódok

A státuszkód három számjegy, és az első számjegy adja a kategóriát.

A gyakorlatban használt kódok

6JSON — az adatcsere formátuma

A JSON (JavaScript Object Notation) egy szöveges adatformátum. A JavaScript objektum-szintaxisából származik, de ma már minden programozási nyelv kezeli.

{
  "id": 42,
  "name": "Mechanikus billentyűzet",
  "price": 34990,
  "inStock": true,
  "discount": null,
  "tags": ["billentyűzet", "gaming"],
  "category": {
    "id": 3,
    "name": "Perifériák"
  }
}

A JSON hat adattípusa

Amit a JSON NEM tud

JSON ↔ JavaScript

// Objektum → JSON-szöveg
const szoveg = JSON.stringify({ nev: "Anna", kor: 17 });
// '{"nev":"Anna","kor":17}'

// JSON-szöveg → objektum
const objektum = JSON.parse('{"nev":"Anna","kor":17}');
// { nev: 'Anna', kor: 17 }

Fontos: a hálózaton szöveg utazik. A JSON.parse és a JSON.stringify a fordítók a szöveg és az objektum között. (Express-szel ezt később nagyrészt automatikusan megkapjuk.)

Miért nem XML?

A JSON előtt az XML (eXtensible Markup Language) volt az adatcsere szabványa — a 2000-es évek web-szolgáltatásai szinte kivétel nélkül ezt használták, és sok vállalati rendszer ma is így beszél. Az XML felépítése ismerős lesz: ugyanolyan elemekből áll, mint a HTML — nyitó és záró tagekből —, csak a tagek nevét te találod ki.

Nézzük meg ugyanazt a terméket mindkét formátumban:

Ugyanaz JSON-ban

{
  "id": 42,
  "name": "Mechanikus billentyűzet",
  "price": 34990,
  "inStock": true,
  "tags": ["billentyűzet", "gaming"],
  "category": { "id": 3, "name": "Perifériák" }
}

Ugyanaz XML-ben

<?xml version="1.0" encoding="UTF-8"?>
<product>
  <id>42</id>
  <name>Mechanikus billentyűzet</name>
  <price>34990</price>
  <inStock>true</inStock>
  <tags>
    <tag>billentyűzet</tag>
    <tag>gaming</tag>
  </tags>
  <category>
    <id>3</id>
    <name>Perifériák</name>
  </category>
</product>

A tartalom pontosan ugyanannyi, a JSON mégis nagyjából feleakkora. Az XML minden adatdarabot kétszer nevez meg (nyitó és záró tag), és a legtöbb API-nál ez a többlet semmit nem ad hozzá.

Négy érdemi különbség

• Az XML-ben minden szöveg. A <price>34990</price> és a <inStock>true</inStock> egyaránt karakterlánc — a fogadó programnak külön kell tudnia, hogy az egyiket számmá, a másikat logikai értékké alakítsa. A JSON-ban a 34990 szám, a true logikai érték: a típus benne van a formátumban.
• A lista nem természetes fogalom az XML-ben. A JSON-nak van tömbje ([…]). Az XML-ben ehhez ki kell találni egy burkoló elemet (<tags>), és megegyezni, hogy az ismétlődő gyerekelemek alkotják a listát. Egyetlen elemnél ráadásul nem is egyértelmű, hogy az lista-e vagy sem.
• Az XML-ben kétféle hely van az adatnak: az elem szövege és az attribútum (<product id="42">). Ezért ugyanazt az adatot többféleképpen lehet leírni, és a két oldalnak meg kell egyeznie, melyiket használják. A JSON-ban erre nincs választás.
• A böngésző és a Node.js JSON-ul beszél. A JSON.parse egy sor, és kész JavaScript-objektumot ad. XML-hez elemző kell, az eredmény pedig egy DOM-fa, amit csomópontonként kell bejárni — jóval több kód ugyanazért az adatért.

7Mi az API, és mi a REST?

Az API (Application Programming Interface) két program közötti „szerződés”: leírja, hogyan lehet egy szolgáltatás funkcióit használni.

A web-API olyan API, amelyet HTTP-n keresztül lehet elérni. Ilyen a REST is.

A REST

A REST (REpresentational State Transfer) egy architekturális stílus, amelyet Roy Fielding írt le 2000-ben, a doktori disszertációjában. Fielding egyike volt a HTTP/1.1 szabvány szerzőinek — a REST tulajdonképpen annak összefoglalása, hogyan van kitalálva a web, és hogyan érdemes ezt az API-knál is követni.

A központi gondolat: minden dolog erőforrás (resource), amelynek van egy címe (URI), és amelyet egységes műveletekkel (HTTP-metódusokkal) kezelünk.

        NEM így gondolkodunk:                      Hanem így:
  "hívjuk meg a termékTörlés()-t"     →     "töröljük a /products/42 erőforrást"
        (műveletközpontú)                      (erőforrás-központú)

8A REST hat alapelve

Fielding hat megszorítást (constraint) fogalmazott meg. Ezek együtt adják a REST-et.

1) Kliens–szerver szétválasztás

A felhasználói felület és az adattárolás külön fejlődik. Ugyanazt az API-t használhatja weboldal, mobilapp és külső partner is.

2) Állapotmentesség (stateless)

A szerver nem tárol munkamenet-állapotot a kérések között. Minden kérésnek magában kell hordoznia mindent, ami a feldolgozásához kell — így a hitelesítő adatot is.

3) Gyorsítótárazhatóság (cacheable)

A válaszok megjelölhetők, hogy eltárolhatók-e és meddig (Cache-Control, ETag). Így a kliens vagy egy köztes réteg (CDN — Content Delivery Network) újra felhasználhatja őket: kevesebb hálózat, gyorsabb alkalmazás.

4) Egységes felület (uniform interface)

Ez a REST védjegye. Négy összetevője:

• erőforrás-azonosítás URI-val (/products/42);
• kezelés reprezentációkon keresztül — JSON-t küldünk és kapunk, nem az adatbázissort;
• önleíró üzenetek — a Content-Type megmondja, mit küldtünk; a státuszkód, mi lett az eredmény;
• HATEOAS — a válasz linkeket is tartalmazhat a lehetséges következő lépésekhez.

5) Rétegzett rendszer (layered system)

A kliens nem tudja (és nem is kell tudnia), hogy közvetlenül a szerverrel beszél-e, vagy egy köztes réteggel (proxy, terheléselosztó, gyorsítótár). Bármikor beszúrható közéjük réteg.

6) Kód igény szerint (code on demand) — opcionális

A szerver futtatható kódot is küldhet a kliensnek (például JavaScriptet). Ez az egyetlen nem kötelező alapelv, és a gyakorlatban ritkán számít az API-knál.

{ "id": 42, "name": "Billentyűzet",
  "_links": { "self": "/api/products/42", "category": "/api/categories/3" } }

Richardson érettségi modell

Hasznos skála arra, „mennyire RESTes” egy API:

9Erőforrás-orientált URL-tervezés

Ez a rész a fejezet legfontosabb gyakorlati tudása.

Alapszabályok

A CRUD-műveletek megfeleltetése

Szűrés, rendezés, lapozás, keresés

Ezek nem külön végpontok, hanem query paraméterek ugyanazon a gyűjteményen:

GET /api/products?categoryId=3              // szűrés
GET /api/products?minPrice=1000&maxPrice=5000
GET /api/products?sort=price&order=asc      // rendezés
GET /api/products?page=2&limit=20           // lapozás
GET /api/products?q=billentyuzet            // keresés
GET /api/products?fields=id,name,price      // mezőválasztás

Lapozásnál a válasz általában metaadatot is tartalmaz:

{
  "data": [ { "id": 21, "name": "…" }, { "id": 22, "name": "…" } ],
  "meta": { "page": 2, "limit": 20, "total": 137, "totalPages": 7 }
}

Amikor a művelet nem fér bele a CRUD-ba

Nem minden művelet „létrehozás/olvasás/módosítás/törlés”. Mit kezdjünk a bejelentkezéssel vagy egy rendelés lemondásával? Két bevett megoldás:

• Alerőforrásként kezeljük: POST /orders/42/cancellation — létrehozunk egy „lemondást”.
• Kivételesen művelet-végpontot használunk: POST /auth/login, POST /orders/42/cancel.

Verziózás

Ha az API úgy változik, hogy a régi kliensek eltörnek, verziózni kell:

10Kérés–válasz példák a webshopból

Termékek listázása

GET /api/v1/products?categoryId=3&limit=2 HTTP/1.1
Host: api.webshop.hu
Accept: application/json

HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": [
    { "id": 42, "name": "Mechanikus billentyűzet", "price": 34990, "inStock": true },
    { "id": 43, "name": "Vezeték nélküli egér",   "price": 12990, "inStock": false }
  ],
  "meta": { "page": 1, "limit": 2, "total": 17 }
}

Új termék létrehozása (adminként)

POST /api/v1/products HTTP/1.1
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

{ "name": "Gamer fejhallgató", "price": 24990, "categoryId": 3 }

HTTP/1.1 201 Created
Location: /api/v1/products/58
Content-Type: application/json

{ "id": 58, "name": "Gamer fejhallgató", "price": 24990, "categoryId": 3,
  "createdAt": "2026-03-15T10:30:00.000Z" }

Hibás adat — validációs hiba

POST /api/v1/products HTTP/1.1
Content-Type: application/json

{ "name": "", "price": -500 }

HTTP/1.1 422 Unprocessable Content
Content-Type: application/json

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "A megadott adatok érvénytelenek.",
    "details": [
      { "field": "name",  "message": "A név megadása kötelező." },
      { "field": "price", "message": "Az ár nem lehet negatív." }
    ]
  }
}

Hiányzó jogosultság

DELETE /api/v1/products/42 HTTP/1.1
Authorization: Bearer <egy sima felhasználó tokenje>

HTTP/1.1 403 Forbidden
Content-Type: application/json

{ "error": { "code": "FORBIDDEN",
    "message": "Ehhez a művelethez adminisztrátori jog szükséges." } }

Van rá szabvány is: RFC 9457 — Problem Details

Ha nem akarsz saját hibaszerkezetet kitalálni, használhatod az RFC 9457 szabványt („Problem Details for HTTP APIs”). Ennél a válasz Content-Type fejléce nem application/json, hanem application/problem+json, a törzs pedig előre megbeszélt mezőneveket használ:

HTTP/1.1 422 Unprocessable Content
Content-Type: application/problem+json

{
  "type":     "https://api.webshop.hu/hibak/ervenytelen-adat",
  "title":    "A megadott adatok érvénytelenek.",
  "status":   422,
  "detail":   "Az ár nem lehet negatív, a név pedig kötelező.",
  "instance": "/api/v1/products",

  // a szabvány engedi, hogy saját mezőkkel bővítsd:
  "errors": [
    { "field": "name",  "message": "A név megadása kötelező." },
    { "field": "price", "message": "Az ár nem lehet negatív." }
  ]
}

Miért jó ez? Mert a mezőnevek nem a te fejedből származnak: egy külső fejlesztő, aki még soha nem látta az API-dat, a Content-Type-ból azonnal tudja, mire számítson. Számos keretrendszerhez létezik hozzá kész kliensoldali kezelő is.

11Előnyök és hátrányok

A REST előnyei

A REST hátrányai

12REST vs. a többiek

13Amiről még hallanod kell

Ezeket most csak megismerjük — a webshop-projektben mindegyikkel dolgozni fogunk.

CORS — Cross-Origin Resource Sharing

A böngésző alapból megtiltja, hogy egy oldal (http://localhost:5173) más eredetű (http://localhost:3000) API-t hívjon. A szervernek külön engedélyt kell adnia erre (Access-Control-Allow-Origin fejléc).

Hitelesítés Bearer tokennel

Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiI1IiwiZXhwIjoxNzQyMH0.abc123def456ghi
                      └───── fejléc ─────┘ └──────────── adat ───────────┘ └── aláírás ──┘
                       melyik algoritmus     ki vagy, meddig érvényes      ezzel ellenőrzi
                       írta alá                                            a szerver

A JWT (JSON Web Token) három, ponttal elválasztott részből áll. Nem titkosított, csak aláírt — bárki elolvashatja a tartalmát, de módosítani nem tudja észrevétlenül.

Rate limiting

Korlátozzuk, hány kérést küldhet valaki adott idő alatt. Túllépés esetén 429 Too Many Requests. Véd a visszaélés és a jelszó-próbálgatás ellen.

HTTPS

Éles rendszerben kötelező. Enélkül a tokened és a jelszavad olvasható a hálózaton.

Dokumentáció — OpenAPI / Swagger

Géppel olvasható leírás az API-ról, amelyből kipróbálható dokumentációs felület és kliens-kódok generálhatók.

14Hogyan próbálj ki egy API-t?

# GET-kérés
curl https://jsonplaceholder.typicode.com/users/1

# GET a fejlécekkel együtt
curl -i https://jsonplaceholder.typicode.com/users/1

# POST JSON-nal (cmd-ben a folytatójel ^, PowerShellben `, Linuxon \)
curl -X POST https://jsonplaceholder.typicode.com/posts ^
  -H "Content-Type: application/json" ^
  -d "{\"title\":\"Teszt\",\"body\":\"Szöveg\",\"userId\":1}"

VS Code REST Client-fájl (keresek.http)

### Felhasználó lekérése
GET https://jsonplaceholder.typicode.com/users/1
Accept: application/json

### Új bejegyzés
POST https://jsonplaceholder.typicode.com/posts
Content-Type: application/json

{ "title": "Teszt", "body": "Szöveg", "userId": 1 }

15Jó és rossz API — gyakori hibák

Gyakori hibák — összefoglalva

16Feladatok

GET  /api/getAllUsers
POST /api/user/delete?id=5
GET  /api/user/5/getOrders
POST /api/login?email=a@b.hu&password=titok123
GET  /api/products/cheap

{
  nev: 'Kovács Anna',
  "kor": 17,
  "aktiv": True,
  "targyak": ["matek", "fizika",],
  // megjegyzés
  "szuletett": 2026-05-14
}

https://jsonplaceholder.typicode.com/users
https://jsonplaceholder.typicode.com/users/3
https://jsonplaceholder.typicode.com/users/3/posts
https://jsonplaceholder.typicode.com/posts?userId=3&_limit=2
https://jsonplaceholder.typicode.com/users/9999

17Önellenőrző kvíz

18Összegzés

19Fogalomtár