559 lines
18 KiB
TeX
559 lines
18 KiB
TeX
|
\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{Hypertext Transfer Protocol}
|
||
|
|
% könnte auch unter in die Sektion API
|
||
|
|
|
||
|
|
Das Hypertext Transfer Protocol (http) ist ein Protokoll zum übertragen von
|
||
|
|
medialen Daten. Ein Webserver hört über den Port 80 auf Anfragen und antwortet.
|
||
|
|
Eine Anfrage besteht aus einer Methode, einem Pfad, Kopfzeilen (\texttt{Header})
|
||
|
|
und Inhalt (\texttt{Body}). Die Methode ist eine Konvention, um zu verdeutlichen
|
||
|
|
was mit der Anfrage geschehen soll. Es können Daten abgefragt (\texttt{GET}),
|
||
|
|
erstellt (\texttt{POST}), aktualisiert (\texttt{PUT}) oder gelöscht werden
|
||
|
|
(\texttt{DELETE}). Der Pfad gibt an, für welche Daten die Methode gelten soll.
|
||
|
|
Die Kopfzeilen beinhalten dabei Metadaten, wie Authentifikationen, \Glspl{cookie},
|
||
|
|
Datentypen (MIME-Types), Sprache und das Anwenderprogramm.
|
||
|
|
|
||
|
|
Der Server antwortet mit einem Statuscode, Kopfzeilen und Inhalt. Der Statuscode
|
||
|
|
teilt mit, ob die Anfrage erhalten wurde ($\geq$ 100), erfolgreich bearbeitet
|
||
|
|
werden konnte ($\geq$ 200), eine Weiterleitung nötig ist ($\geq$ 300),
|
||
|
|
die Anfrage einen Fehler enthält ($\geq$ 400) oder
|
||
|
|
ein interner Serverfehler aufgetreten ist ($\geq$ 500). In den Kopfzeilen können
|
||
|
|
Berechtigungen gesetzt werden, welche festlegen, wie mit den Daten
|
||
|
|
umzugehen ist.
|
||
|
|
|
||
|
|
\newpage
|
||
|
|
\subsection{Geräte} \label{Geräte}
|
||
|
|
Die \Gls{gpodder}, welche wir für unser Produkt verwenden und erweitern, bietet eine gerätespezifische
|
||
|
|
Synchronisation an. Diese bieten wir jedoch nicht an, denn wir synchronisieren Änderungen aller
|
||
|
|
Geräte gleichwertig mit dem Nutzeraccount.
|
||
|
|
Deshalb werden Geräte innerhalb der API ignoriert.
|
||
|
|
|
||
|
|
\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}
|
||
|
|
{
|
||
|
|
email: "jeff@example.com",
|
||
|
|
password: "MyNameIsJeff"
|
||
|
|
}
|
||
|
|
\end{routeRequestBody}
|
||
|
|
\end{routeRequest}
|
||
|
|
\begin{routeResponse}{application/json}
|
||
|
|
\begin{routeResponseItem}{200}
|
||
|
|
{OK: Nutzer wurde erfolgreich angelegt.}
|
||
|
|
\end{routeResponseItem}
|
||
|
|
|
||
|
|
\begin{routeResponseItem}{400}
|
||
|
|
{Bad Request: Fehler beim Parsen der Anfrage}
|
||
|
|
\end{routeResponseItem}
|
||
|
|
\end{routeResponse}
|
||
|
|
\end{apiRoute}
|
||
|
|
|
||
|
|
\newpage
|
||
|
|
|
||
|
|
\subsubsection{Anmelden}\label{a:login}
|
||
|
|
|
||
|
|
\begin{apiRoute}{post}{/api/2/auth/\{username\}/login.json}
|
||
|
|
{Gegebenen Nutzer des gegebenen Geräts mithilfe HTTP Basic Auth einloggen.}
|
||
|
|
\begin{pathParameter}
|
||
|
|
\pathParamItem{username}{Nutzername des einzuloggenden Nutzers}
|
||
|
|
\end{pathParameter}
|
||
|
|
\begin{routeResponse}{application/json}
|
||
|
|
\begin{routeResponseItem}{200}
|
||
|
|
{OK: Die Responseheader haben ein gesetztes Session-ID \Gls{cookie}.}
|
||
|
|
\end{routeResponseItem}
|
||
|
|
|
||
|
|
\begin{routeResponseItem}{400}
|
||
|
|
{Bad Request: Der Client stellt einen \Gls{cookie} für einen falschen Nutzer bereit.}
|
||
|
|
\end{routeResponseItem}
|
||
|
|
|
||
|
|
\begin{routeResponseItem}{401}
|
||
|
|
{Unauthorized: Zugriff ohne Anmeldedaten}
|
||
|
|
\end{routeResponseItem}
|
||
|
|
\end{routeResponse}
|
||
|
|
\end{apiRoute}
|
||
|
|
|
||
|
|
\subsubsection{Abmelden}\label{a:logout}
|
||
|
|
|
||
|
|
\begin{apiRoute}{post}{/api/2/auth/\{username\}/logout.json}
|
||
|
|
{Löscht den \Gls{cookie} beim Client.}
|
||
|
|
\begin{pathParameter}
|
||
|
|
\pathParamItem{username}{Nutzername des betreffenden Nutzers}
|
||
|
|
\end{pathParameter}
|
||
|
|
\begin{routeResponse}{application/json}
|
||
|
|
\begin{routeResponseItem}{200}
|
||
|
|
{OK: Falls der Client keinen \Gls{cookie} gesendet hat oder der Nutzer
|
||
|
|
erfolgreich ausgeloggt wurde.}
|
||
|
|
\end{routeResponseItem}
|
||
|
|
|
||
|
|
\begin{routeResponseItem}{400}
|
||
|
|
{Bad Request: Der Client stellt einen \Gls{cookie} für den falschen Nutzer bereit.}
|
||
|
|
\end{routeResponseItem}
|
||
|
|
\end{routeResponse}
|
||
|
|
\end{apiRoute}
|
||
|
|
|
||
|
|
\newpage
|
||
|
|
|
||
|
|
\subsubsection{Passwort ändern}\label{a:changepassword}
|
||
|
|
|
||
|
|
\begin{apiRoute}{put}{/api/2/auth/\{username\}/changepassword.json}
|
||
|
|
{Passwort des gegebenen Nutzer ändern, indem altes und neues Passwort
|
||
|
|
übergeben werden. }
|
||
|
|
\begin{pathParameter}
|
||
|
|
\pathParamItem{username}{Nutzername des betreffenden Nutzers}
|
||
|
|
\end{pathParameter}
|
||
|
|
\begin{routeRequest}{application/json}
|
||
|
|
\begin{routeRequestBody}
|
||
|
|
{
|
||
|
|
password: "MyPasswordWasLeaked",
|
||
|
|
new_password: "SoIMadeANewOne"
|
||
|
|
}
|
||
|
|
\end{routeRequestBody}
|
||
|
|
\end{routeRequest}
|
||
|
|
\begin{routeResponse}{application/json}
|
||
|
|
\begin{routeResponseItem}{200}
|
||
|
|
{OK: Die Responseheader haben ein gesetztes Session-ID \Gls{cookie}.}
|
||
|
|
\end{routeResponseItem}
|
||
|
|
|
||
|
|
\begin{routeResponseItem}{400}
|
||
|
|
{Bad Request: Der Client stellt einen \Gls{cookie} für einen falschen Nutzer bereit.}
|
||
|
|
\end{routeResponseItem}
|
||
|
|
|
||
|
|
\begin{routeResponseItem}{401}
|
||
|
|
{Unauthorized: Zugriff ohne Anmeldedaten}
|
||
|
|
\end{routeResponseItem}
|
||
|
|
\end{routeResponse}
|
||
|
|
\end{apiRoute}
|
||
|
|
|
||
|
|
\subsubsection{Passwort vergessen}\label{a:forgot}
|
||
|
|
|
||
|
|
\begin{apiRoute}{post}{/api/2/auth/forgot.json}
|
||
|
|
{Sende eine E-Mail zum Zurücksetzen des Passworts. }
|
||
|
|
\begin{routeRequest}{application/json}
|
||
|
|
\begin{routeRequestBody}
|
||
|
|
{
|
||
|
|
email: "jeff@example.com"
|
||
|
|
}
|
||
|
|
\end{routeRequestBody}
|
||
|
|
\end{routeRequest}
|
||
|
|
\begin{routeResponse}{application/json}
|
||
|
|
\begin{routeResponseItem}{200}
|
||
|
|
{OK: E-Mail wurde erfolgreich versendet.}
|
||
|
|
\end{routeResponseItem}
|
||
|
|
|
||
|
|
\begin{routeResponseItem}{400}
|
||
|
|
{Bad Request: Fehler beim Parsen der Anfrage}
|
||
|
|
\end{routeResponseItem}
|
||
|
|
\end{routeResponse}
|
||
|
|
\end{apiRoute}
|
||
|
|
|
||
|
|
\newpage
|
||
|
|
\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}
|
||
|
|
|
||
|
|
\newpage
|
||
|
|
\subsubsection{Account löschen}\label{a:delete}
|
||
|
|
|
||
|
|
\begin{apiRoute}{delete}{/api/2/auth/\{username\}/delete.json}
|
||
|
|
{Der Account des gegebenen Nutzers wird gelöscht.}
|
||
|
|
\begin{pathParameter}
|
||
|
|
\pathParamItem{username}{Nutzername des zu löschenden Nutzers.}
|
||
|
|
\end{pathParameter}
|
||
|
|
\begin{routeRequest}{application/json}
|
||
|
|
\begin{routeRequestBody}
|
||
|
|
{
|
||
|
|
password: "APasswordIWontHaveToRememberAnymore"
|
||
|
|
}
|
||
|
|
\end{routeRequestBody}
|
||
|
|
\end{routeRequest}
|
||
|
|
\begin{routeResponse}{application/json}
|
||
|
|
\begin{routeResponseItem}{200}
|
||
|
|
{OK: Der Account des gegebenen Nutzers wurde erfolgreich gelöscht.}
|
||
|
|
\end{routeResponseItem}
|
||
|
|
|
||
|
|
\begin{routeResponseItem}{400}
|
||
|
|
{Bad Request: Der Client stellt einen \Gls{cookie} für einen falschen Nutzer bereit.}
|
||
|
|
\end{routeResponseItem}
|
||
|
|
|
||
|
|
\begin{routeResponseItem}{401}
|
||
|
|
{Unauthorized: Zugriff ohne Anmeldedaten}
|
||
|
|
\end{routeResponseItem}
|
||
|
|
\end{routeResponse}
|
||
|
|
\end{apiRoute}
|
||
|
|
|
||
|
|
\newpage
|
||
|
|
\subsection{Subscriptions API}\label{a:subs}
|
||
|
|
\subsubsection{Abrufen aller \Glspl{abo}}\label{a:getSubs}
|
||
|
|
|
||
|
|
\begin{apiRoute}{get}{/subscriptions/\{username\}.json}{/subscriptions/\{username\}/\{deviceid\}.json}
|
||
|
|
\begin{pathParameter}
|
||
|
|
\pathParamItem{username}{Nutzername des betreffenden Nutzers}
|
||
|
|
\pathParamItem{deviceid}{siehe~\nameref{Geräte}}
|
||
|
|
\end{pathParameter}
|
||
|
|
|
||
|
|
\begin{urlParameter}
|
||
|
|
\urlParamItem{jsonp}{\Gls{JSONP} wird nicht unterstützt und der Parameter entsprechend ignoriert.}
|
||
|
|
\end{urlParameter}
|
||
|
|
|
||
|
|
\begin{routeResponse}{application/json}
|
||
|
|
|
||
|
|
\begin{routeResponseItem}{200}
|
||
|
|
{OK: \Glspl{abo} werden im \Gls{json}-Format zurückgegeben.}
|
||
|
|
\begin{routeResponseItemBody}
|
||
|
|
[
|
||
|
|
"http://example.org/feed.rss",
|
||
|
|
"http://example.org/podcast.php",
|
||
|
|
"http://example.org/foo"
|
||
|
|
]
|
||
|
|
\end{routeResponseItemBody}
|
||
|
|
\end{routeResponseItem}
|
||
|
|
|
||
|
|
\begin{routeResponseItem}{400}{Bad Request: falsches Format}
|
||
|
|
\end{routeResponseItem}
|
||
|
|
|
||
|
|
\begin{routeResponseItem}{401}
|
||
|
|
{Unauthorized: falscher Nutzer oder nicht eingeloggt}
|
||
|
|
\end{routeResponseItem}
|
||
|
|
|
||
|
|
\end{routeResponse}
|
||
|
|
\end{apiRoute}
|
||
|
|
|
||
|
|
\newpage
|
||
|
|
\subsubsection{Abrufen der Informationen aller \Glspl{abo}}\label{a:getTitles}
|
||
|
|
|
||
|
|
\begin{apiRoute}{get}{/subscriptions/titles/\{username\}.json}{/subscriptions/\{username\}/\{deviceid\}.json}
|
||
|
|
|
||
|
|
\begin{pathParameter}
|
||
|
|
\pathParamItem{username}{Nutzername des betreffenden Nutzers}
|
||
|
|
\end{pathParameter}
|
||
|
|
\begin{routeResponse}{application/json}
|
||
|
|
|
||
|
|
\begin{routeResponseItem}{200}
|
||
|
|
{OK: \Glspl{abo} werden im angefragten Format zurückgegeben. Dabei werden für ein \Gls{abo} nur die aktuellsten 20 \Glspl{episode} zurückgegeben.}
|
||
|
|
\begin{routeResponseItemBody}
|
||
|
|
[
|
||
|
|
{
|
||
|
|
"url": "http://example.com/podcast.php",
|
||
|
|
"title": "This is a cool podcast"
|
||
|
|
"timestamp": "2009-12-12T09:00:00",
|
||
|
|
"episodes": [
|
||
|
|
{
|
||
|
|
"podcast": "http://example.org/podcast.php",
|
||
|
|
"episode": "http://ftp.example.org/foo.ogg",
|
||
|
|
"title": "Episode 1: My journy",
|
||
|
|
"timestamp": "2009-12-12T09:00:00",
|
||
|
|
"guid": "AU-20190814-1342-5100-A",
|
||
|
|
"action": "play",
|
||
|
|
"started": 15,
|
||
|
|
"position": 120,
|
||
|
|
"total": 500
|
||
|
|
}
|
||
|
|
]
|
||
|
|
}
|
||
|
|
]
|
||
|
|
\end{routeResponseItemBody}
|
||
|
|
\end{routeResponseItem}
|
||
|
|
|
||
|
|
\begin{routeResponseItem}{400}{Bad Request: falsches Format}
|
||
|
|
\end{routeResponseItem}
|
||
|
|
|
||
|
|
\end{routeResponse}
|
||
|
|
|
||
|
|
\end{apiRoute}
|
||
|
|
\newpage
|
||
|
|
|
||
|
|
\subsubsection{\Glspl{abo} hochladen}\label{a:uploadSubs}
|
||
|
|
|
||
|
|
\begin{apiRoute}{put}{/subscriptions/\{username\}/\{deviceid\}.json}
|
||
|
|
{Falls bereits \Glspl{abo} im Nutzeraccount vorhanden, werden diese
|
||
|
|
zusammengeführt.}
|
||
|
|
|
||
|
|
\begin{pathParameter}
|
||
|
|
\pathParamItem{username}{Nutzername des betreffenden Nutzers}
|
||
|
|
\pathParamItem{deviceid}{siehe~\nameref{Geräte}}
|
||
|
|
\end{pathParameter}
|
||
|
|
|
||
|
|
\begin{routeResponse}{application/json}
|
||
|
|
\begin{routeResponseItem}{200}
|
||
|
|
{OK: \Glspl{abo} wurden aktualisiert und leerer String wird zurückgegeben.}
|
||
|
|
\end{routeResponseItem}
|
||
|
|
|
||
|
|
\begin{routeResponseItem}{400}{Bad Request: falsches Format}
|
||
|
|
\end{routeResponseItem}
|
||
|
|
|
||
|
|
\begin{routeResponseItem}{401}{Unauthorized: falscher Nutzer}
|
||
|
|
\end{routeResponseItem}
|
||
|
|
\end{routeResponse}
|
||
|
|
\end{apiRoute}
|
||
|
|
|
||
|
|
\subsubsection{Abrufen von \Gls{abo}-Änderungen}\label{a:getSubDelta}
|
||
|
|
|
||
|
|
\begin{apiRoute}{get}{/api/2/subscriptions/\{username\}/\{deviceid\}.json}
|
||
|
|
{}
|
||
|
|
|
||
|
|
\begin{pathParameter}
|
||
|
|
\pathParamItem{username}{Nutzername des betreffenden Nutzers}
|
||
|
|
\pathParamItem{deviceid}{siehe~\nameref{Geräte}}
|
||
|
|
\end{pathParameter}
|
||
|
|
|
||
|
|
\begin{urlParameter}
|
||
|
|
\urlParamItem{since}{Timestamp-Wert der letzten Antwort}
|
||
|
|
\end{urlParameter}
|
||
|
|
|
||
|
|
\begin{routeResponse}{application/json}
|
||
|
|
|
||
|
|
\begin{routeResponseItemBody}
|
||
|
|
{
|
||
|
|
"add": [
|
||
|
|
"http://example.com/feed.rss",
|
||
|
|
"http://example.org/podcast.php"
|
||
|
|
],
|
||
|
|
"remove": ["http://example.net/foo.xml"],
|
||
|
|
"timestamp": 12347
|
||
|
|
}
|
||
|
|
\end{routeResponseItemBody}
|
||
|
|
\end{routeResponse}
|
||
|
|
|
||
|
|
\end{apiRoute}
|
||
|
|
|
||
|
|
\newpage
|
||
|
|
\subsubsection{Änderungen der \Glspl{abo} hochladen}\label{a:applySubDelta}
|
||
|
|
|
||
|
|
\begin{apiRoute}{post}{/api/2/subscriptions/\{username\}/\{deviceid\}.json}
|
||
|
|
{}
|
||
|
|
|
||
|
|
\begin{pathParameter}
|
||
|
|
\pathParamItem{username}{Nutzername des betreffenden Nutzers}
|
||
|
|
\pathParamItem{deviceid}{siehe~\nameref{Geräte}}
|
||
|
|
\end{pathParameter}
|
||
|
|
|
||
|
|
\begin{routeRequest}{application/json}
|
||
|
|
\begin{routeRequestBody}
|
||
|
|
{
|
||
|
|
"add": [
|
||
|
|
"http://example.com/feed.rss",
|
||
|
|
"http://example.org/podcast.php"
|
||
|
|
],
|
||
|
|
"remove": ["http://example.net/foo.xml"]
|
||
|
|
}
|
||
|
|
\end{routeRequestBody}
|
||
|
|
\end{routeRequest}
|
||
|
|
|
||
|
|
\begin{routeResponse}{application/json}
|
||
|
|
\begin{routeResponseItem}{200}{OK: \Glspl{abo} wurden aktualisiert.}
|
||
|
|
\begin{routeResponseItemBody}
|
||
|
|
{
|
||
|
|
"timestamp": 1337,
|
||
|
|
"update_urls": []
|
||
|
|
}
|
||
|
|
\end{routeResponseItemBody}
|
||
|
|
``update\textunderscore urls'' wird nicht bereitgestellt, deshalb
|
||
|
|
wird eine leere Liste zurückgegeben.
|
||
|
|
\end{routeResponseItem}
|
||
|
|
\begin{routeResponseItem}{400}{Bad Request: falsches Format}
|
||
|
|
\end{routeResponseItem}
|
||
|
|
\end{routeResponse}
|
||
|
|
\end{apiRoute}
|
||
|
|
|
||
|
|
\newpage
|
||
|
|
\subsection{Episode Action API}\label{a:episodeActions}
|
||
|
|
|
||
|
|
\subsubsection{Episode Actions hochladen}\label{a:uploadEpisodeActions}
|
||
|
|
|
||
|
|
\begin{apiRoute}{post}{/api/2/episodes/\{username\}.json}
|
||
|
|
{}
|
||
|
|
|
||
|
|
\begin{pathParameter}
|
||
|
|
\pathParamItem{username}{Nutzername des betreffenden Nutzers}
|
||
|
|
\end{pathParameter}
|
||
|
|
|
||
|
|
\begin{routeRequest}
|
||
|
|
|
||
|
|
\begin{routeRequestBody}
|
||
|
|
POST /api/2/episodes/some-user.json
|
||
|
|
[
|
||
|
|
{
|
||
|
|
"podcast": "http://example.org/podcast.php",
|
||
|
|
"episode": "http://ftp.example.org/foo.ogg",
|
||
|
|
"title": "Episode 1: My journey",
|
||
|
|
"timestamp": "2009-12-12T09:00:00"
|
||
|
|
"guid": "AU-20190814-1342-5100-A",
|
||
|
|
"action": "play",
|
||
|
|
"started": 15,
|
||
|
|
"position": 120,
|
||
|
|
"total": 500
|
||
|
|
}
|
||
|
|
]
|
||
|
|
|
||
|
|
\end{routeRequestBody}
|
||
|
|
|
||
|
|
\end{routeRequest}
|
||
|
|
|
||
|
|
\begin{jsonKeys}
|
||
|
|
\jsonKeyItem{podcast}{Feed-URL des \Glspl{podcast} zu welchem die \Gls{episode} gehört (erforderlich)}
|
||
|
|
\jsonKeyItem{episode}{Medien-URL der \Gls{episode} (erforderlich)}
|
||
|
|
\jsonKeyItem{device}{Geräte-ID auf welcher die Aktion stattfand.}
|
||
|
|
\jsonKeyItem{action}{Eins von: download, play, delete, new (erforderlich)}
|
||
|
|
\jsonKeyItem{timestamp}{UTC-Timestamp im ISO 8601 Format, wann die Aktion stattfand}
|
||
|
|
\jsonKeyItem{started}{Position in Sekunden, an welcher das Anhören der \Gls{episode} gestartet wurde (nur bei Aktion: play)}
|
||
|
|
\jsonKeyItem{position}{Position in Sekunden, an welcher das Anhören der \Gls{episode} gestoppt wurde (nur bei Aktion: play)}
|
||
|
|
\jsonKeyItem{total}{Länge der \Gls{episode} (nur bei Aktion: play)}
|
||
|
|
|
||
|
|
\end{jsonKeys}
|
||
|
|
|
||
|
|
\begin{routeResponse}{application/json}
|
||
|
|
\begin{routeResponseItem}{200}{OK}
|
||
|
|
\begin{routeResponseItemBody}
|
||
|
|
{
|
||
|
|
"timestamp": 1337,
|
||
|
|
"update_urls": []
|
||
|
|
}
|
||
|
|
\end{routeResponseItemBody}
|
||
|
|
``update\textunderscore urls'' wird nicht bereitgestellt, deshalb
|
||
|
|
wird eine leere Liste zurückgegeben.
|
||
|
|
\end{routeResponseItem}
|
||
|
|
\end{routeResponse}
|
||
|
|
\end{apiRoute}
|
||
|
|
|
||
|
|
\subsubsection{Abrufen von Episode Actions}\label{a:getEpisodeActions}
|
||
|
|
|
||
|
|
\begin{apiRoute}{get}{/api/2/episodes/\{username\}.json}
|
||
|
|
{}
|
||
|
|
|
||
|
|
\begin{pathParameter}
|
||
|
|
\pathParamItem{username}{Nutzername des betreffenden Nutzers}
|
||
|
|
\end{pathParameter}
|
||
|
|
|
||
|
|
\begin{urlParameter}
|
||
|
|
\urlParamItem{podcast (string)}{URL des \Glspl{podcast}; falls gesetzt, werden nur Aktionen der \Glspl{episode} des gegebenen \Glspl{podcast} zurückgegeben.}
|
||
|
|
\urlParamItem{device (string)}{Device-ID; siehe~\nameref{Geräte}}
|
||
|
|
\urlParamItem{since (int)}{Nur \Glspl{episode}-Aktionen ab dem gegebenen Timestamp werden zurückgegeben.}
|
||
|
|
\urlParamItem{aggregated (bool)}{Wird ignoriert. }
|
||
|
|
\end{urlParameter}
|
||
|
|
|
||
|
|
\begin{routeResponse}{application/json}
|
||
|
|
\begin{routeResponseItem}{200}{OK}
|
||
|
|
\begin{routeResponseItemBody}
|
||
|
|
{
|
||
|
|
"actions": [
|
||
|
|
{
|
||
|
|
"podcast": "http://example.org/podcast.php",
|
||
|
|
"episode": "http://ftp.example.org/foo.ogg",
|
||
|
|
"title": "Episode 1: My journey",
|
||
|
|
"timestamp": "2009-12-12T09:00:00"
|
||
|
|
"guid": "AU-20190814-1342-5100-A",
|
||
|
|
"action": "play",
|
||
|
|
"started": 15,
|
||
|
|
"position": 120,
|
||
|
|
"total": 500
|
||
|
|
}
|
||
|
|
],
|
||
|
|
"timestamp": 12345
|
||
|
|
}
|
||
|
|
\end{routeResponseItemBody}
|
||
|
|
\end{routeResponseItem}
|
||
|
|
\end{routeResponse}
|
||
|
|
\end{apiRoute}
|
||
|
|
|