139 lines
6.9 KiB
TeX
139 lines
6.9 KiB
TeX
\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}
|