\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}