Mi a webes API?

Célok

A lecke végére meg tudod mondani, mi a webes API, miben más, mint egy HTML-oldal, mit jelent az API-szerződés, és miért igényel egy API is hozzáférés-ellenőrzést.

Miért van szükség API-ra?

Eddig a szerver HTML-oldalakat adott, amelyeket a böngésző megjelenített. De a szolgáltatásnak sokféle fogyasztója lehet: a böngészőben futó program, egy mobilalkalmazás, egy másik szerver, egy adatelemző szkript. Ezeknek nem megjelenített oldalra, hanem adatra és műveletekre van szükségük, olyan formában, amit program dolgozhat fel. Az API ilyen, programok számára kialakított kapcsolódási pont. Ha minden kliensnek külön „kézzel” kellene kifürkésznie a szolgáltatás belsejét, a rendszer törékeny lenne; az API meghatározza, mit lehet kérni, és mit lehet válaszul várni.

A webes API olyan API, amely webes technológiákon, jellemzően HTTP-n keresztül érhető el. Nem külön hálózati protokoll a HTTP helyett: ugyanazokat a kéréseket, metódusokat, státuszkódokat és fejléceket használja (2. fejezet).

A kurzuslista két fogyasztója

Egy egyetemi szolgáltatás a kurzusokat weboldalon és mobilalkalmazásban is megmutatja. A két felület eltérő, de ugyanazokra a kurzusadatokra épülhet. A szerver az API-n át adja vissza az adatot, a kliens pedig a saját felületéhez illő módon jeleníti meg.

flowchart LR
    W[Webes kliens] --> A[Kurzus API]
    M[Mobil kliens] --> A
    A --> S[Alkalmazási szabályok és adatok]

Az ábra közös kapcsolódási pontot mutat. Nem jelenti, hogy minden kliens ugyanazt a képernyőt jeleníti meg, és azt sem, hogy az API az adatbázis tábláit változtatás nélkül teszi közzé: az API mögött ellenőrzés, jogosultság és üzleti szabály is működik.

Íme egy kérés és válasz a Kurzuspont egyszerűsített API-jához (a kipróbáló szerver kimenete, lerövidítve):

$ curl -i http://localhost:8081/api/kurzusok/webprog
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{"id":"webprog","cim":"Webprogramozás 1.","ferohely":40,"jelentkezett":31}

A fejléc application/json típusa jelzi, hogy a törzs strukturált adat. A kliens a cim mezőt kiolvassa és megjeleníti.

Mit jelent a „szerződés”?

Az API szerződése (contract) azt írja le, milyen műveletek érhetők el, milyen útvonalon és HTTP-metódussal, milyen adatot fogad a kérés, milyen szerkezetű a válasz, milyen státuszkódokat és hibákat adhat. Amikor a kliens erre a megállapodásra épít, a szerver és a kliens külön fejleszthető. Ha a szerver váratlanul más mezőnevet küld, a kliens felülete elromolhat akkor is, ha a hálózat és a HTTP hibátlanul működik (ezt az 5.6 lecke részletezi).

A szerződés nem feltétlenül gépi nyelven leírt, de a dokumentáció mindenképp része. A kliensnek tudnia kell, milyen adat kötelező, mi hiányozhat, hogyan jelez a szerver hibát, és melyik verzióra számíthat.

Adat és megjelenítés szétválasztása

Ha a szerver HTML-oldalt küld, a megjelenítés nagy része a válaszban van. Egy adat-API rendszerint strukturált adatot ad, amelyből a kliens építi fel a felületet vagy a további feldolgozást. A szétválasztás rugalmasságot ad (ugyanaz az adat többféle felületen), de új felelősségeket is: a kliensnek kezelnie kell a betöltési állapotot, a hibát és a hiányzó adatot; a szervernek stabil, érthető szerződést kell kínálnia.

Nyilvános és belső API

Végigvezetett példa: a Kurzuspont API-ja

A Kurzuspont két kliense: a böngészős felület és egy hallgatói mobilalkalmazás. Mindkettő ugyanazt a GET /api/kurzusok kérést használja, és ugyanazokat a mezőket kapja. A szerződés a következőket rögzíti:

Elem	Szerződés
Végpont	GET /api/kurzusok a lista, GET /api/kurzusok/{id} egy kurzus
Válasz	JSON, id, cim, ferohely, jelentkezett mezőkkel
Hiba	státuszkód + JSON-hibatörzs
Hozzáférés	a lista nyilvános, a jelentkezés bejelentkezést kér

A fejlesztő a következő lépésekben a formátumot (5.2), az erőforrásmodellt (5.3) és a változások kezelését (5.5, 5.6) határozza meg. (Az id itt szándékosan azonosító szöveg, nem szám.)

Gyakori tévhitek

Állítás	Pontosítás
„Az API egy adatbázis közvetlen megnyitása az internetre.”	A szolgáltatás a saját szabályai szerint ad adatot és műveletet.
„Az API a HTTP helyett működik.”	A webes API jellemzően HTTP-üzeneteket használ.
„Az API csak mobilalkalmazásoknak kell.”	Böngészős, szerveroldali és más kliensek is használják.
„Ha a válasz 200, a kliens biztosan érti.”	A válasz szerkezetének is meg kell felelnie a szerződésnek.
„A nem nyilvános API nem igényel védelmet.”	A belső API-t is jogosultság-ellenőrzés védi.

Röviden

• A webes API programok számára kialakított, HTTP-n elérhető kapcsolódási pont.
• A szerződés rögzíti a végpontokat, a bemenetet, a választ és a hibákat.
• Az API szétválasztja az adatot a megjelenítéstől, ezért több kliens kiszolgálható.
• A nyilvános és a belső API is igényel azonosítást és jogosultság-ellenőrzést.

Ellenőrző kérdések

1. Miben különbözik egy API-válasz egy HTML-oldal válaszától?
2. Mit tartalmaz az API-szerződés?
3. Miért romolhat el egy kliens, ha a szerver átnevez egy mezőt?
4. Miért kell egy belső API-t is védeni?

Tanulási források

• Overview of HTTP (MDN) — a HTTP szerepe webes kommunikációban angolul.
• REST (MDN szójegyzék) — a RESTful API-k rövid meghatározása.