third week

órai anyagok/week03/sections/01-rest-api.tex

@@ -0,0 +1,138 @@
+\section{REST API alapok}
+
+\begin{frame}{Mi az API?}
+\footnotesize
+Az \textbf{API} (Application Programming Interface) egy megállapodás arról, hogyan kommunikálhat egymással két szoftverkomponens -- anélkül, hogy az egyiknek ismernie kellene a másik belső működését. Amikor a telefonodon megnyitod egy időjárás-alkalmazást, az alkalmazás egy API-n keresztül kér adatot egy távoli szervertől; neked (és az alkalmazásnak) fogalma sincs, hogyan tárolja a szerver az adatokat belül -- csak azt kell tudnia, milyen kérést küldjön, és milyen választ várhat.
+
+\begin{itemize}
+\item Egyértelmű, dokumentált "szerződés" a kliens és a szerver között
+\item Elrejti a belső implementációs részleteket (adatbázis típusa, kód szerkezete, stb.)
+\item Web API-k esetén jellemzően HTTP felett kommunikálunk -- ez az, amit az elmúlt órán megismertünk
+\end{itemize}
+
+\begin{block}{REST -- egy konkrét API-stílus}
+A \textbf{REST} (Representational State Transfer) nem egy protokoll vagy szabvány, hanem egy architekturális stílus, amit Roy Fielding írt le 2000-ben a doktori disszertációjában. Ma a legelterjedtebb módja a web API-k tervezésének.
+\end{block}
+\end{frame}
+
+\begin{frame}{Mitől "RESTful" egy API?}
+\footnotesize
+Fielding öt fő elvet fogalmazott meg, amiknek egy API-nak meg kell felelnie ahhoz, hogy igazán RESTfulnek nevezzük. A gyakorlatban a legtöbb "REST API"-nak nevezett rendszer csak részben követi ezeket -- de minél többet betartunk belőlük, annál kiszámíthatóbb és skálázhatóbb lesz az API-nk.
+
+\begin{itemize}
+\item \textbf{Kliens-szerver:} a kliens és a szerver különálló felelősséggel bír, egymástól függetlenül fejleszthetők
+\item \textbf{Állapotmentesség (statelessness):} minden kérés önmagában tartalmaz minden szükséges információt -- ezt már az 1. héten megismertük a HTTP-nél
+\item \textbf{Cache-elhetőség:} a válaszoknak jelezniük kell, hogy gyorsítótárazhatók-e (pl. \texttt{Cache-Control} header)
+\item \textbf{Egységes interfész (uniform interface):} az erőforrásokat egységes módon, azonosítható URL-eken keresztül érjük el
+\item \textbf{Rétegzett rendszer:} a kliens nem tudja (és nem is kell tudnia), hogy közvetlenül a szerverrel, vagy egy köztes rétegen (pl. load balancer, cache) keresztül kommunikál-e
+\end{itemize}
+\end{frame}
+
+\begin{frame}[fragile]{Erőforrás-orientált URL tervezés}
+\footnotesize
+Az URL-ek \emph{erőforrásokat} (főneveket) azonosítsanak, ne \emph{műveleteket} (igéket) -- a műveletet úgyis a HTTP metódus fejezi ki.
+
+\begin{block}{Rossz gyakorlat (igealapú URL)}
+\begin{verbatim}
+GET /getAllUsers
+POST /createNewUser
+POST /deleteUser?id=123
+\end{verbatim}
+\end{block}
+
+\begin{block}{Jó gyakorlat (erőforrás-alapú, többes szám)}
+\begin{verbatim}
+GET    /users          # osszes felhasznalo
+POST   /users          # uj felhasznalo letrehozasa
+GET    /users/123      # egy adott felhasznalo
+DELETE /users/123      # felhasznalo torlese
+\end{verbatim}
+\end{block}
+\end{frame}
+
+\begin{frame}{CRUD $\to$ HTTP metódus megfeleltetés}
+\footnotesize
+Ez a táblázat gyakorlatilag a REST API tervezés "alaptörvénye" -- ha ezt következetesen betartod, az API-d azonnal ismerős és kiszámítható lesz bárki számára, aki már használt REST API-t.
+
+\begin{tabular}{|l|l|l|}
+\hline
+\textbf{Művelet} & \textbf{HTTP metódus} & \textbf{Végpont példa} \\
+\hline
+Create (létrehozás) & POST & \texttt{POST /users} \\
+Read (egy elem) & GET & \texttt{GET /users/123} \\
+Read (lista) & GET & \texttt{GET /users} \\
+Update (teljes) & PUT & \texttt{PUT /users/123} \\
+Update (részleges) & PATCH & \texttt{PATCH /users/123} \\
+Delete (törlés) & DELETE & \texttt{DELETE /users/123} \\
+\hline
+\end{tabular}
+
+\begin{block}{Emlékeztető az 1. hétről}
+GET, PUT, DELETE idempotensek -- többszöri hívás ugyanazt az állapotot eredményezi. A POST nem az.
+\end{block}
+\end{frame}
+
+\begin{frame}{Richardson Maturity Model}
+\footnotesize
+Leonard Richardson egy szintekre bontott modellt alkotott, amivel megmérhető, mennyire "RESTful" valójában egy API. A legtöbb valós API a 2. szinten áll -- ez teljesen elfogadható, a 3. szint (HATEOAS) ritkán éri meg a többletbonyolultságot.
+
+\begin{itemize}
+\item \textbf{0. szint:} egyetlen végpont, minden művelet ugyanazon keresztül megy (pl. RPC-szerű, SOAP-hoz hasonló stílus)
+\item \textbf{1. szint:} külön erőforrások, saját URL-lel, de a HTTP metódusokat még nem használjuk következetesen
+\item \textbf{2. szint:} erőforrások + helyesen használt HTTP metódusok és státuszkódok -- \emph{ez a gyakorlatban elterjedt "REST API" szint}
+\item \textbf{3. szint (HATEOAS):} a válasz linkeket is tartalmaz a kapcsolódó műveletekhez, így a kliensnek nem kell előre tudnia az összes URL-t
+\end{itemize}
+\end{frame}
+
+\begin{frame}[fragile]{API verziózás}
+\footnotesize
+Az API-k idővel változnak -- új mezők, módosított viselkedés. Ha egy változás nem visszafelé kompatibilis, szükség van egy módra, hogy a régi klienseket ne törjük el. Erre szolgál a verziózás.
+
+\begin{block}{URL-alapú verziózás (leggyakoribb)}
+\begin{verbatim}
+GET /api/v1/users/123
+GET /api/v2/users/123
+\end{verbatim}
+Egyszerű, jól látható, könnyen tesztelhető Postmanben is.
+\end{block}
+
+\begin{block}{Header-alapú verziózás}
+\begin{verbatim}
+GET /api/users/123
+Accept: application/vnd.myapp.v2+json
+\end{verbatim}
+"Tisztább" URL-eket eredményez, de nehezebb böngészőből tesztelni.
+\end{block}
+\end{frame}
+
+\begin{frame}[fragile]{Lapozás, szűrés, rendezés}
+\footnotesize
+Amikor egy erőforrásból (pl. felhasználók) több ezer is lehet, nem küldhetjük vissza mindet egyszerre -- ezt oldják meg a query paraméterek, amikkel a kliens finomíthatja, pontosan mit szeretne kapni.
+
+\begin{verbatim}
+GET /users?page=2&limit=20
+GET /users?role=admin
+GET /users?sort=-createdAt
+GET /users?search=alice
+\end{verbatim}
+
+\begin{itemize}
+\item \textbf{Lapozás (pagination):} \texttt{page}/\texttt{limit} vagy \texttt{offset}/\texttt{limit} párokkal
+\item \textbf{Szűrés (filtering):} egy adott mező szerinti szűkítés (\texttt{role=admin})
+\item \textbf{Rendezés (sorting):} \texttt{sort=mezonev}, mínusz előjellel csökkenő sorrend
+\end{itemize}
+\end{frame}
+
+\begin{frame}{Összefoglalás -- REST API}
+\footnotesize
+\begin{block}{REST API tervezés}
+\begin{itemize}
+\item API: szerződés két rendszer kommunikációjához; REST: egy elterjedt architekturális stílus rá
+\item Fielding elvei: kliens-szerver, statelessness, cache-elhetőség, egységes interfész, rétegzettség
+\item URL-ek: erőforrások (főnevek, többes szám), nem műveletek (igék)
+\item CRUD $\to$ HTTP metódus: POST/GET/PUT/PATCH/DELETE következetesen
+\item Richardson Maturity Model: a legtöbb API a 2. szinten van, ez rendben van
+\item Verziózás: URL vagy header alapon; lapozás/szűrés/rendezés: query paraméterekkel
+\end{itemize}
+\end{block}
+\end{frame}