Initial commitHEADmain

1 files changed, 191 insertions, 0 deletions

diff --git a/20-implementierungsheft/sections/apidoc.tex b/20-implementierungsheft/sections/apidoc.tex
new file mode 100644
index 0000000..0cce48c
--- /dev/null
+++ b/20-implementierungsheft/sections/apidoc.tex
@@ -0,0 +1,191 @@
+\newenvironment{urlParameter}
+{
+	\newcommand{\urlParamItem}[2]
+	{
+		\rowcolor{\methodLightColor} ##1 & ##2 \\
+	}
+	\newcommand{\noUrlParameter}[1]
+	{
+		\small{\textit{##1}}
+	}
+	%\vspace{-0.61em}
+	
+	\arrayrulecolor{\methodColor}
+	
+	\begin{tabularx}{\textwidth}{X}
+		\rowcolor{\methodLightColor!20}
+		\textbf{URL-Parameter} \\ \hline
+	\end{tabularx}
+	
+	\tabularx{\textwidth}{l X}
+}
+
+\newenvironment{pathParameter}
+{
+	\newcommand{\pathParamItem}[2]
+	{
+		\rowcolor{\methodLightColor} ##1 & ##2 \\
+	}
+	\newcommand{\noPathParameter}[1]
+	{
+		\small{\textit{##1}}
+	}
+	%\vspace{-0.61em}
+	
+	\arrayrulecolor{\methodColor}
+	
+	\begin{tabularx}{\textwidth}{X}
+		\rowcolor{\methodLightColor!20}
+		\textbf{Pfad-Parameter} \\ \hline
+	\end{tabularx}
+	
+	\tabularx{\textwidth}{l X}
+}
+
+\newenvironment{jsonKeys}
+{
+	\newcommand{\jsonKeyItem}[2]
+	{
+		\rowcolor{\methodLightColor} ##1 & ##2 \\
+	}
+	\newcommand{\nojsonKeys}[1]
+	{
+		\small{\textit{##1}}
+	}
+	%\vspace{-0.61em}
+	
+	\arrayrulecolor{\methodColor}
+	
+	\begin{tabularx}{\textwidth}{X}
+		\rowcolor{\methodLightColor!20}
+		\textbf{Json-Keys} \\ \hline
+	\end{tabularx}
+	
+	\tabularx{\textwidth}{l X}
+}
+
+\section{\Gls{api}}
+
+\subsection{Authentication API}\label{a:auth}
+
+\subsubsection{Registrierung}\label{a:register}
+
+\begin{apiRoute}{post}{/api/2/auth/register.json}
+    {Registriert einen Nutzer mit einer E-Mail-Adresse und Passwort.
+    
+	Versendet E-Mail mit Bestätigungslink an die angegebene E-Mail-Adresse.}
+    \begin{routeRequest}{application/json}
+            \begin{routeRequestBody}
+{
+	username: "jeff"
+    email: "jeff@example.com",
+    password: "MyNameIsJeff"
+}
+            \end{routeRequestBody}
+    \end{routeRequest}
+    \begin{routeResponse}{application/json}
+        \begin{routeResponseItem}{200}
+            {OK: Nutzer wurde erfolgreich angelegt und E-Mail versendet.}
+        \end{routeResponseItem}
+
+        \begin{routeResponseItem}{400}
+            {Bad Request: Fehler beim Parsen oder Eingabe nicht anforderungsgemäß.}
+        \end{routeResponseItem}
+    \end{routeResponse}
+\end{apiRoute}
+
+Es wird nun sowohl ein Benutzername als auch eine E-Mail-Adresse für einen Nutzer gespeichert.
+Der Benutzername wird in der Folge für die Authentifizierung und die Zuordnung der Anfragen verwendet.
+Die E-Mail-Adresse wird vor dem Speichern mit einem festen Geheimschlüssel gesalted und gehashed.
+Sie ist zum Ableich der bei der bei (ref an forgot) anzugebenden E-Mail-Adresse
+
+\newpage
+\subsubsection{E-Mail verifizieren}\label{a:resetpassword}
+
+\begin{apiRoute}{get}{/api/2/auth/\{username\}/verify.json}
+    {Verifiziere die bei der Registrierung angegebene E-Mail-Adresse durch diese, per E-Mail versendete, URL.}
+    \begin{pathParameter}
+        \pathParamItem{username}{Nutzername des betreffenden Nutzers}
+    \end{pathParameter}
+    \begin{urlParameter}
+        \urlParamItem{token}{JSON-Web-Token (24h gültig)}
+    \end{urlParameter}
+    \begin{routeResponse}{application/json}
+        \begin{routeResponseItem}{200}
+            {OK: Der Benutzer wurde erfolgreich aktiviert und kann sich nun anmelden.}
+        \end{routeResponseItem}
+
+        \begin{routeResponseItem}{400}
+            {Bad Request: Der Nutzer mit dem angegebenen Namen ist bereits verifiziert. }
+        \end{routeResponseItem}
+
+        \begin{routeResponseItem}{401}
+            {Unauthorized: Der JWT ist ungültig. }
+        \end{routeResponseItem}
+
+		\begin{routeResponseItem}{404}
+            {Not Found: Es exisitiert kein Nutzer mit dem angegebenen Benutzernamen. }
+        \end{routeResponseItem}
+    \end{routeResponse}
+\end{apiRoute}
+
+Dieser Endpunkt wurde zur Verifizierung der bei der Registrierung angegebenen E-Mail-Adresse hinzugefügt.
+Nach der Registrierung wird dem Benutzer eine E-Mail mit der URL dieses Endpunkts (inklusive Benutzernamen und JWT) 
+zugesendet. Klickt der Benutzer auf den Link wird die Anfrage im Backend verarbeitet und der Nutzer automatisch
+zum Webfrontend weitergeleitet. Erst nach der Verifizierung der E-Mail-Adresse ist die Registrierung vollständig
+abgeschlossen und der Account aktiviert - nun kann sich der Nutzer anmelden.
+
+\newpage
+\subsubsection{Passwort vergessen}\label{a:forgot}
+
+\begin{apiRoute}{post}{/api/2/auth/\{email\}/forgot.json}
+    {Sende eine E-Mail zum Zurücksetzen des Passworts.}
+	\begin{pathParameter}
+        \pathParamItem{email}{E-Mail-Adresse des betreffenden Nutzers}
+    \end{pathParameter}
+    \begin{routeResponse}{application/json}
+        \begin{routeResponseItem}{200}
+            {OK: E-Mail wurde erfolgreich versendet.}
+        \end{routeResponseItem}
+
+        \begin{routeResponseItem}{404}
+            {Not Found: Es exisitiert kein Nutzer mit der angegeben E-Mail-Adresse.}
+        \end{routeResponseItem}
+    \end{routeResponse}
+\end{apiRoute}
+
+Die E-Mail-Adresse des Benutzers, der sein Passwort vergessen hat, wird nicht mehr im Request-Body
+als \GLS{json}-Payload, sondern als Pfadvariable in der URL übergeben. 
+
+\subsubsection{Passwort zurücksetzen}\label{a:resetpassword}
+
+\begin{apiRoute}{put}{/api/2/auth/\{username\}/resetpassword.json}
+    {Passwort des gegebenen Nutzers ändern nachdem dieser sein Passwort
+    vergessen hat. }
+    \begin{pathParameter}
+        \pathParamItem{username}{Nutzername des betreffenden Nutzers}
+    \end{pathParameter}
+    \begin{urlParameter}
+        \urlParamItem{token}{JSON-Web-Token}
+    \end{urlParameter}
+    \begin{routeRequest}{application/json}
+            \begin{routeRequestBody}
+{
+    password: "APasswordIWontForgetAgain"
+}
+            \end{routeRequestBody}
+    \end{routeRequest}
+    \begin{routeResponse}{application/json}
+        \begin{routeResponseItem}{200}
+            {OK: Das Passwort wurde erfolgreich geändert.}
+        \end{routeResponseItem}
+
+        \begin{routeResponseItem}{400}
+            {Bad Request: Fehler beim Parsen der Anfragen. }
+        \end{routeResponseItem}
+
+        \begin{routeResponseItem}{401}
+            {Unauthorized: JWT ist ungültig. }
+        \end{routeResponseItem}
+    \end{routeResponse}
+\end{apiRoute}
\ No newline at end of file