Auflistung aller REST URLs um Anfragen an den Server zu stellen. Beachte: Jede URL beginnt mit /rest/ und gibt standardmäßig ein JSON Objekt zurück. Jede Methode kann auch anstelle von /rest/ mit /rest/xml/ aufgerufen werden. Es wird dann ein XML als Antwort gegeben.

Übersicht

URL Methode Beschreibung Status Priorität
Anfragen
/search GET Freitextsuche nach allen Arten von Objekten (MediaItems, Events, User..) unnötig? 10
/search/mediaItem GET Parametrisierte Suche nach MediaItems fertig -
/search/user GET Parametrisierte Suche nach Usern fertig -
/artist/{ id } GET Gibt Artist mit angegebener id zurück fertig -
/search/tag GET Gibt eine Liste mit (lexikograohisch ähnlichen) Tags zurück fertig -
/mediaItem/{ id } GET Gibt mediaItem mit angegebener id zurück fertig -
/historyItem/{ id } GET Gibt HistoryItem mit angegebener id zurück fertig -
/user/{ nickOrId } GET Gibt User mit angegebener nickOrId zurück fertig -
/user/{ id }/friends GET Gibt die Freunde von User mit Id id zurück fertig -
/user/{ id }/ownPendingRequests GET Gibt die User zurück, an die der User mit Id id eine Freundschaftsanfrage gesendet hat fertig -
/user/{ id }/history GET Gibt einen Teil der History von User mit Id id zurück fertig -
/user/{ id }/lists GET Gibt alle Listen zurück die ein Nutzer angelegt hat fertig -
/user/{ id }/list/{ listname } GET Gibt die benutzerdefinierten Favoritenliste listname des Benutzers mit Id id zurück fertig -
Hinzufügen
/user/{ id }/uploadProfilePic POST Läd ein Bild als Profilbild für den User id hoch fertig -
/new/artist POST Fügt neuen Artist in DB ein. fertig -
/new/mediaItem POST Fügt neues MediaItem hinzu. fertig -
/mediaItem/{ id }/addChild GET Verknüpft zwei vorhandene MedaItems in einer Parent-Child Beziehung fertig -
/new/historyItem POST Fügt neues HistoryItem hinzu. (=Tracken) fertig -
/new/user POST Fügt neuen User hinzu. (= Registrieren) fertig -
/new/list GET Fügt bei einem Nutzer eine neue MediaItem-Liste hinzu fertig -
Manipulieren
/artist/{ id }/update POST Aktualisiert vorhandenen Artist id (zB. Biographie geändert) fertig -
/mediaItem/{ id }/update POST Aktualisiert vorhandenes MediaItem id (zB. Beschreibung geändert) fertig -
/mediaItem/{ id }/doTag GET Fügt dem MediaItem mit Id id ein Tag hinzu fertig -
/user/{ id }/update POST Aktualisiert vorhandenen User mit Id id fertig -
Löschen
/mediaItem/{ id }/detachChild GET Löst eine Parent-Child verbindung zwischen zwei MediaItems auf fertig -
/delete/historyItem_id GET Löscht bei einem Nutzer ein HistoryItem aus seiner History fertig -
/delete/list GET Löscht bei einem Nutzer eine exisiterende MediaItem-Liste fertig -
Sonstiges
/login POST Prüft ob Password und Nutzername im übersendeten User objekt zusammen passen und erteilt im Erfolgsfall ein Token. fertig -
/logout/{ id } GET Prüft ob Token und NutzerId zusammen passen und löscht im Erfolgsfall das Token. fertig -
/user/{ id }/requestFriendship GET Stellt eine Freundschaftsanfrage. fertig -
/user/{ id }/acceptFriendship GET Nimmt eine Freundschaftsanfrage an. fertig -
/user/{ id }/declineFriendship GET Lehnt eine Freundschaftsanfrage ab. fertig -
/user/{ id }/cancelFriendship GET Bricht eine Freundschaftsbeziehung ab. fertig -
/user/{ id }/withdrawFriendshipRequest GET Zieht eine Freundschaftsanfrage zurück. fertig -

Weitere zugehörige Wikiseiten

Response StatusCode

Details

Anfragen

/search/mediaItem

Parametrisierte Suche nach einer Menge von MediaItems. Alle Parameter werden mit UND verknüpft, so dass die Elemente der Ergebnismenge alle Parameter erfüllen. Außnahme bildet id . Werden keine Parameter oder nur type angegeben, so wird die Anfrage nicht weiter bearbeitet und als Antwort wird "HTTP/1.1 412 Precondition Failed" mit StatusCode "NOT_ENOUGH_PARAMETERS_SET" gesendet.

Parameter Optional [Default] Typ Bemerkung
id ja Long Wird dieser Parameter angegeben, werden alle anderen ignoriert. In der Ergebnismenge ist nur das MediaItem mit der Id id , falls es dieses gibt.
name ja String Es wird nach MediaItems gesucht, deren Name name enthält
artist ja String Es wird nach MediaItems gesucht, die von einem Artist mit Namen artist erstellt wurden
desc ja String Es wird nach MediaItems gesucht, deren short oder longDescription desc enthält
tags ja String Es wird nach MediaItmes gesucht, die mit mindestens einem der angegebenen Tags markiert wurden. Beispiel: tags=nerdy:book:2010
type ja String Es wird nach MediaItems gesucht, die den MediaType mit dem Kennzeichner type haben
page ja [0] Int Der pageoffset. Muss >= 0 sein
resultsPerPage ja [30] Int Die maximale Anzahl der zurückzugebenden Objekte. Muss zwischen [0,150] liegen

Beispielanfrage: ~/rest/search/mediaItem;name=geschicht;tags=epochal:funny;type=book

/search/user

Parametrisierte Suche nach einer Menge von MediaItems. Alle Parameter werden mit UND verknüpft, so dass die Elemente der Ergebnismenge alle Parameter erfüllen. Außnahme bildet id. Werden keine Parameter angegeben, so wird die Anfrage nicht bearbeitet weiter und als Antwort wird "HTTP/1.1 412 Precondition Failed" mit StatusCode "NOT_ENOUGH_PARAMETERS_SET" gesendet.

Parameter Optional [Default] Typ Bemerkung
id ja Long Wird dieser Parameter angegeben, werden alle anderen ignoriert. In der Ergebnismenge ist nur der User mit der Id id , falls es diesen gibt.
name ja String Es wird nach Usern gesucht, deren Name name enthält
nick ja String Es wird nach Usern gesucht, deren Nickname nick enthält
page ja [0] Int Der pageoffset. Muss >= 0 sein
resultsPerPage ja [30] Int Die maximale Anzahl der zurückzugebenden Objekte. Muss zwischen [0,150] liegen

Beispielanfrage: ~/rest/search/user;name=mann;page=4;resultsPerPage=50

/search/tag

Rückgabe ist eine Liste von Tags, sortiert nach Verwendungshäufigkeit, in denen der tag (als Präfix) vorkommt. Diese Suche kann vor allem dazu verwendet werden um dem User Vorschläge anzubieten, wenn er etwas taggen möchte.

Parameter Optional [Default] Typ Bemerkung
tag ja String Der Name des Tags, nach dem gesucht werden soll.
page ja [0] Int Der pageoffset. Muss >= 0 sein
resultsPerPage ja [30] Int Die maximale Anzahl der zurückzugebenden Objekte. Muss zwischen [0,150] liegen

/user/{ nickOrId }

Gibt alle vorhandenen Attribute (bis auf password etc.) zu einem einzelnen User zurück dessen id oder nick genau dem Parameter nickOrId entspricht.

Parameter Optional [Default] Typ Bemerkung
nickOrId nein String Der Nickname oder die Id desjenigen Users, zu dem die Daten abgerufen werden sollen.
token nein String Das Token, welches der anfragende User beim login oder beim Ändern des Passwortes zugesendet bekam.

Beispielanfrage: ~/rest/user/Paul;token= oder ~/rest/user/23;token=

Beachte: User, die keine Freunde des Users nickOrId sind, erhalten keine Auskunft über diese Methode.

/user/{ id }/friends

Gibt die Freundesliste des Users mit der Id id zurück. Sie enthält diejenigen User, mit denen der User id eine Freundschaftsbeziehung mit gewissem Status hat. Siehe Parameter status .

Parameter Optional [Default] Typ Bemerkung
id nein long Gibt die id desjenigen Users an, dessen Freunde angezeigt werden sollen.
status ja [accepted] String Freundschaftsstatus. Mögliche Werte sind: "pending", "accepted", "declined", "withdrawn"
page ja [0] Int Der pageoffset. Muss >= 0 sein
resultsPerPage ja [30] Int Die maximale Anzahl der zurückzugebenden Objekte. Muss zwischen [0,150] liegen
token nein String Das Token, welches der anfragende User beim login oder beim Ändern des Passwortes zugesendet bekam.

Beispielanfrage: ~/rest/user/3/friends;status=pending;page=2;resultsPerPage=50;token=

Beachte: Bei status=accepted werden alle bestätigten Freundschaften angezeigt, ganz gleich, welcher der beiden Usern die Anfrage gestellt hat. Bei status=pending werden alle noch nicht bestätigten Freundschaften angezeigt, bei denen der Angefragt derjenige ist, der die id id hat. Bei status=declined werden alle Freundschaften angezeigt, die der User mit id id abgelehnt hat. Bei status=withdrawn werden alle Freundschaften angezeigt, die der User mit id id zurückgezogen hat, bevor die Freundschaft vom anderen bestätigt oder abgelehnt wurde. Die Freundesliste für den Status accepted darf nur von Usern abgerufen werden, die mit dem User id befreundet sind. Alle anderen Listen, sind nur dem User id selbst zugänglich.

/user/{ id }/ownPendingRequests

Gibt diejenigen User zurück, an die der User mit Id id eine Freundschaftsanfrage versendet hat und die noch nicht beantwortet wurde (Status Pending hat).

Parameter Optional [Default] Typ Bemerkung
id nein long Gibt die id desjenigen Users an, dessen angefragte Freunde angezeigt werden sollen.
page ja [0] Int Der pageoffset. Muss >= 0 sein
resultsPerPage ja [30] Int Die maximale Anzahl der zurückzugebenden Objekte. Muss zwischen [0,150] liegen
token nein String Das Token, welches der anfragende User beim login oder beim Ändern des Passwortes zugesendet bekam.

Beispielanfrage: ~/rest/user/3/ownPendingRequests;page=1;resultsPerPage=20;token=

Beachte: Diese Anfrage kann nur von dem User id gestellt werden.

/user/{ id }/history

Gibt die Tracking History des Users mit der Id id zurück.

Parameter Optional [Default] Typ Bemerkung
id nein long Gibt die id desjenigen Users an, von dem die History angezeigt werden soll.
type ja Long Gibt an, ob nur HistoryItems eines bestimmten Typs gesucht werden sollen. Mögliche Werte: "music", "web", "movie", "tv", "book", "paper", "videogame", "game"
start ja Long Gibt den Anfang des Intervalls an, indem die Items gesucht werden. Für die gefundenen Items i gilt: i.start >= start
end ja Long Gibt das Emde des Intervalls an, indem die Items gesucht werden. Für die gefundenen Items i gilt: i.end <= end
orderBy ja [end_desc] String Die Ergebnisliste kann geordnet werden. Mögliche Werte sind: "start_asc", "end_asc", "id_asc", "name_asc", "start_desc", "end_desc", "id_desc", "name_desc"
status ja [accepted] String Es wird nach HistoryItems gesucht, an denen der User id teilgenommen hat. Soll nach Events gesucht werden, denen er abgesagt hat, oder noch nicht zugesagt kann dieser Parameter angepasst werden. Mögliche Werte sind: "pending", "accepted", "declined", "ignored"
page ja [0] Int Der pageoffset. Muss >= 0 sein
resultsPerPage ja [30] Int Die maximale Anzahl der zurückzugebenden Objekte. Muss zwischen [0,150] liegen
token nein String Das Token, welches der anfragende User beim login oder beim Ändern des Passwortes zugesendet bekam.

Beispielanfrage: ~/rest/user/3/history;orderBy=name_asc;token=

Beachte: Diese Anfrage ist nur Freunden des Users id zugänglich.

/user/{ id }/lists

Gibt alle benurzererstellten Listen eines Nutzers zurück. Pro Liste werden jedoch maxmimal die ersten 20 MediaItems zurückgegeben.

Parameter Optional [Default] Typ Bemerkung
id nein long Gibt die id desjenigen Users an, von dem die Listen angezeigt werden sollen.
maxLength ja Int Pro Liste werden die maxLength ersten Elemente zurückgeben, vorraussgesetzt es gibt so viele.
token nein String Das Token, welches der anfragende User beim login oder beim Ändern des Passwortes zugesendet bekam.

Beispielanfrage: ~/rest/xml/user/1/lists;maxLength=5;token=

Beachte: Diese Anfrage ist nur Freunden des Users id zugänglich.

/user/{ id }/history

Gibt die TrackingHistory des Users zurück. Enthalten sind alle HistoryItems, die der User selbst getrackt hat, sowie diejenigen, an denen er sonst noch teilgenommen hat. Siehe Parameter status .

Parameter Optional [Default] Typ Bemerkung
id nein long Gibt die id desjenigen Users an, von dem die History angezeigt werden soll.
type ja Long Gibt an, ob nur HistoryItems eines bestimmten Typs gesucht werden sollen. Mögliche Werte: "music", "web", "movie", "tv", "book", "paper", "videogame", "game"
start ja Long Gibt den Anfang des Intervalls an, indem die Items gesucht werden. Für die gefundenen Items i gilt: i.start >= start
end ja Long Gibt das Emde des Intervalls an, indem die Items gesucht werden. Für die gefundenen Items i gilt: i.end <= end
orderBy ja [end_desc] String Die Ergebnisliste kann geordnet werden. Mögliche Werte sind: "start_asc", "end_asc", "id_asc", "name_asc", "start_desc", "end_desc", "id_desc", "name_desc"
status ja [accepted] String Es wird standardmäßig nach HistoryItems gesucht, an denen der User id teilgenommen hat. Soll nach Events gesucht werden, denen er abgesagt hat, oder noch nicht zugesagt kann dieser Parameter angepasst werden. Wird dieser Parameter angegeben, so werden ausschließlich Events anderer User angezeigt, an denen der User mit dem angegebenen Status teilgenommen hat. Mögliche Werte sind: "pending", "accepted", "declined", "ignored"
page ja [0] Int Der pageoffset. Muss >= 0 sein
resultsPerPage ja [30] Int Die maximale Anzahl der zurückzugebenden Objekte. Muss zwischen [0,150] liegen
token nein String Das Token, welches der anfragende User beim login oder beim Ändern des Passwortes zugesendet bekam.

Beispielanfrage: ~/rest/user/3/history;orderBy=name_asc;token=

Beachte: Diese Anfrage ist nur Freunden des Users id zugänglich.

Hinzufügen

/user/{ id }/uploadProfilePic

Mit dieser Methode kann ein Profilbild für den Nutzer angelegt werden.

Parameter Optional [Default] Typ Bemerkung
id nein long Gibt die id desjenigen Users an, dessen Profilbild gespeichert werden soll.
token nein String Das Token, welches der anfragende User beim login oder beim Ändern des Passwortes zugesendet bekam.

Beispielanfrage:
POST /mediaTrack/rest/user/<id>/uploadProfilePic HTTP/1.1
Host: <serveradresse>:<port>
Accept: application/json
Content-Type: multipart/form-data; boundary=---------------------------670564796321
Content-Length: 51752

   -----------------------------670564796321
   Content-Disposition: form-data; name="userPicture"; filename="<filename>.jpg"
   Content-Type: image/jpeg
   
   <PictureAsBytes...>
   -----------------------------670564796321--

Beachte: Der Content-Type des POST Requests muss immer mulitpart/form-data sein. Als mögliche Content-Types der einzelnen Content-Parts sind nur image/* gültig. (image/jpeg , image/png wären gültige Types). Es wird immer nur das erste gesendete File betrachtet. Werden mehrere gesendet werden die restlichen ignoriert. Maximale Dateigröße beträgt 1024kb.

/new/artist

Fügt einen neuen Artist in die DB ein. Existiert bereits ein Artist mit gleichem Namen, so wird eine Meldung gegeben, man überprüfen soll, ob der vorhandene Artist evtl. derjenige ist, den man einfügen möchte oder dass der Artist über das Attribut disambiguation näher spezifiziert werden soll. Existiert ein Artist bei dem beides Übereinstimmt, so wird vorgeschlagen eine andere disambiguation anzugeben, falls es sich nicht um den vorhandenen Artist handelt.

Zusätlich zu dem im HTTP-Content gesendeten Objekt müssen noch folgende URL Parameter angeben werden:
Parameter Optional [Default] Typ Bemerkung
userId nein long Gibt die id desjenigen Users an, der das MediaItem hinzufügt.
token nein String Das Token, welches der anfragende User beim login oder beim Ändern des Passwortes zugesendet bekam.

Ein Artist hat folgenden beispielhaften Aufbau: (als JSON. XML analog)
{"artist":{
   "beginDate":852073200000,
   "created":1280567937000,
   "lastUpdated":1280566935000,
   "name":"MIA.",
   "disambiguation":"German rock\/pop group",
   "bio":"MIA. (mit Punkt; auch Mia. geschrieben) sind eine deutsche Elektropop-Musikgruppe.\n\nBandgeschichte:\n\nMIA. gründeten sich 1997 in Berlin als Schülerband. Mieze, 1979 in Berlin geboren, und Andi Ross (später Andy Penn, ebenfalls 1979 in Berlin geboren), die gemeinsam das John-Lennon-Gymnasium in Berlin besuchten, wurden von ihrer Mitschülerin Sarah Kuttner an Robert „Bob“ Schütze und Ingo Puls vermittelt."
   "type":"BAND",
   "id":47,
   "beginDate":<timeInMilis since 1970>,
   "endDate":<timeInMilis since 1970>,
   "works":{
      "work"[
         { <MediaItemRepresentation> },
         { <MediaItemRepresentation> },
         { <MediaItemRepresentation> }
         ]
      },
   "simpleWorks":"<mediaItemId>:<mediaItemId>: ... :<MediaItemId>"
}   }

Beispielanfrage: ~rest/new/artist

POST /mediaTrack/rest/new/artist HTTP/1.1
Host: <serveradresse>:<port>
Content-Type: application/json

{"artist":{
   "name":"Blumentopf",
   "type":"BAND",
   "beginDate":852073200000,
   "bio":"Blumentopf ist eine deutsche Hip-Hop-Band aus München. Ihr erstes Album Kein Zufall veröffentlichten sie 1997 über Four Music, wo sie bis heute unter Vertrag stehen. Mittlerweile gilt die Band als eine der besten Live-Bands des Genres. Ihnen wurde 2001 und 2002 von den Lesern der Hip-Hop-Zeitschrift Juice der Titel 'Beste Live-Band' verliehen. In Hip-Hop-Kreisen wird die Band vor allem auch für das hohe Niveau ihrer Texte und Reime geschätzt."
   "simpleWorks":"2323:123:991:2184:238:23111:34"
}   }

Beachte: Um einen Artist hinzuzufügen, sind die Attribute created, lastUpdated, id nicht notwendig, sie werden sogar überschrieben. Die Attibtue name und type sind NICHT optional. disambiguation ist meist optional, nur dann nicht, wenn es schon einen Artist mit gleichem name gibt. works, beginDate und endDate sind optional. Ist beginDate nach endDate, so wird der Artist nicht einfgefügt - eine Fehlermeldung wird ausgegeben.

/new/mediaItem

Hinter der URL /new/mediaItem verbergen sich acht weitere URLs, mit denen man spezifizieren kann, was genau hinzugefügt werden soll. Alle Aufrufe sind POST-Requests. Die JSON- bzw. XML-Objekte, die empfangen werden, haben bis auf spezielle Attribute die gleichen Felder, die (bis auf name) optional gesetzt werden können:
Attribut Typ Bemerkung
name String Der Name des neuen Items
duration Long Die Dauer in millisekunden
published Long Das Datum, an dem das zu Grunde liegende MediaItem erschienen ist
artistIds List Eine Liste der Id's der Artists, die mit diesem MediaItem assoziiert werden sollen
ean String Die EAN des MediaItems
isbn String Die ISBN-10 oder ISBN-13 des MediaItems. Im Falle der ISBN-13 wird diese als EAN interpretiert
shortDescription String Eine Kurzbeschreibung / Abstract des MediaItems
longDescription String Eine ausführliche Beschreibung

Zusätlich zu dem im HTTP-Content gesendeten Objekt müssen noch folgende URL Parameter angeben werden:
Parameter Optional [Default] Typ Bemerkung
userId nein long Gibt die id desjenigen Users an, der das MediaItem hinzufügt.
token nein String Das Token, welches der anfragende User beim login oder beim Ändern des Passwortes zugesendet bekam.

Beachte: Die URL /new/mediaItem existiert alleine nicht!

.../book

Fügt ein neues Buch in die Datenbank ein. Die Erklärung hier ist etwas ausführlicher wie bei den weiteren MediaItems, da diese analog funktionieren.

Zusätzliche Attribute zum MediaItem:
Attribut Typ Bemerkung
subtitle String Untertitel des Buches
pages Integer Anzahl der Seiten

Beispielanfrage: ~/rest/new/mediaItem/book
POST /mediaTrack/rest/new/mediaItem/book HTTP/1.1
Host: <serveradresse>:<port>
Content-Type: application/json
Content-Length: 274

{   "book":{
      "name":"Swarm Intelligence",
      "subTitle":"Introduction and Applications",
      "longDescription":"The laws that govern the collectiove behavior of social insects [...]",
      "ean":"9783540740889",
      "pages":284,
      "tags":{
         "tag":[
            {"name":"Science"},
               {"name":"Swarm Intelligence"},
            {"name":"Artificial Intelligence"},
            {"name":"Computer Science"}
            ]
      },
      "picUrl":<url-to-Picture>
}   }

Wird folgendes Ergebnis liefern:
{   "response":{"@totalResultCount":"1","@statusCode":"CREATED","@page":"0","@maxPage":"0",
      "content":{
         "item":{"@type":"xmlBook",
            "created":1279012731000,
            "duration":0,
            "ean":9783540740889,
            "id":28,
            "lastUpdated":1279012731000,
            "longDescription":"The laws that govern the collectiove behavior of social insects [...]",
            "name":"Swarm Intelligence",
            "type":"book",
            "pages":284,
            "picUrl":<url-to-Picture>,
            "tags":{
               "tag":[
                  {"name":"Science", "useCount":216},
                  {"name":"Swarm Intelligence", "useCount":2},
                  {"name":"Artificial Intelligence", "useCount":4},
                  {"name":"Computer Science", "useCount":80}
               ]
}   }   }   }   }

.../game

Fügt ein neues Spiel in die Datenbank ein. Es handelt sich explizit nicht um VideoSpiele/Computerspiele etc. sondern vielmehr um Brett- oder Kartenspiele.

Zusätzliche Attribute zum MediaItem:
Attribut Typ Bemerkung
maxPlayers Integer Maximale Anzahl der Mitspieler

.../movie

Fügt einen neuen Film in die Datenbank ein. Es handelt sich vorwiegend um Kinofilme oder große TV-Produktionen. Explizit sind damit keine Serien etc. gemeint.

Zusätzliche Attribute zum MediaItem:
Attribut Typ Bemerkung
subtitle String Untertitel des Filmes

.../music

Fügt ein neues Lied in die Datenbank ein.

Zusätzliche Attribute zum MediaItem:
Attribut Typ Bemerkung
musicType String Art dieses MediaItems. Mögliche Werte sind "collection" und "track". Defaultwert ist "track".

.../paper

Fügt einen neuen Artikel oder ähnliches in die Datenbank ein. Es handelt sich beispielsweise um einen Artikel in einer Zeitung/Zeitschrift. Auch wiss. Veröffentlichungen finden hier Platz.

Zusätzliche Attribute zum MediaItem: Keine

.../tv

Fügt eine neue TV-Serie in die Datenbank ein.

Zusätzliche Attribute zum MediaItem:
Attribut Typ Bemerkung
tvType String Art der Sendung. Mögliche werte sind: "series", "season", "episode", "show", "other"
seasonNumber Integer Nummer der Staffel. (Bei TvType= "episode" ist die Nummer der zugeordneten Staffel einzutragen)
episodeNumber Integer Nummer der Folge.

.../videogame

Fügt eine neues Video-Spiel oder ähnliches in die Datenbank ein. Hier finden sich alle Computer- und Konsolenspiele.

Zusätzliche Attribute zum MediaItem: Keine

.../web

Fügt eine neue Web-Seite in die Datenbank ein.

Zusätzliche Attribute zum MediaItem:
Attribut Typ Bemerkung
url URL-String Die URL der Webseite, auf die bezug genommen wird.

< a name="mediaItem_id_addChild">/mediaItem/{ id }/addChild

Fügt dem MediaItem id ein untergeordnetes MediaItem als Kind hinzu.

Parameter Optional [Default] Typ Bemerkung
id nein long Die Id des MediaItems, dem ein MediaItem untergeordnet werden soll.
childId nein long Die Id des MediaItems, das hinzugefügt werden soll.

/new/historyItem

Fügt ein HistoryItem der DatenBank hinzu.

Parameter Optional [Default] Typ Bemerkung
token nein String Das Token, welches der anfragende User beim login oder beim Ändern des Passwortes zugesendet bekam.

Beispielanfrage: ~/rest/new/historyItem;token=
POST /mediaTrack/rest/new/historyItem HTTP/1.1
Host: <serveradresse>:<port>
Content-Type: application/json

{"historyItem":{
   "name":"reading",
   "initiator":{
      "id":3
      },
   "mediaItem":{
      "id":11
      },
   "trackingSoftware":"<deineTrackerId>"
}   }

Wird folgendes Ergebnis liefern:

{"response":{"@totalResultCount":"1","@statusCode":"OK","@page":"0","@maxPage":"0",
   "content":{
      "item":{"@type":"xmlHistoryItem",
         "created":0,
         "endDate":1281784620000,
         "id":40,
         "initiator":{
            "id":1,
            "nick":"user1"
         },
         "lastUpdated":0,
         "mediaItem":{
            "id":11,
            "name":"Die Unendliche Geschichte",
            "tags":{
               "tag":[
                  {"name":"funny"},
                  {"name":"epochal"},
                  {"name":"book"}
               ]
            },
            "type":"book"
         },
         "name":"reading",
         "startDate":1281784620000
}   }   }   }

Attribut Typ Bemerkung
name String Name des Trackingeintrags. Falls dieser nicht gesendet wird, wird der Name des MediaItems übernommen.
initiator JSON Das User-Objekt des Trackers. Es wird nur die Id benötigt
mediaItem JSON Das MediaItem-Objekt, um das es sich dreht. Es wird nur die Id benötigt.
longitude Double Die geographische Länge
latitude Double Die geographische Breite
startDate Long Startzeitpunkt
endDate Long Endzeitpunkt
trackingSoftware String Eindeutige IdentifizierungsID der verwendeten Trackingsoftware

Beachte: Das übersendete historyItem muss mindestens einen gülitgen Initiator (= id von denjenigem, der das Item trackt) und ein mediaItem (auch hier langt die Id) haben. Ebenso unabdingbar ist die Angabe der trackingSoftware . Der Rest wird vom Server ausgefüllt. Optional hingegen sind name , longitude , latitude , startDate , endDate . Wird nur eins von longitude und latitude angegeben, so wird dieses Attribut ignoriert. Bei start und end kann auch nur eins angegeben werden. Das jeweils andere wird durch die standardmäßige Dauer des zu Grunde liegenden MediaItems errechnet. Werden startDate / endDate nicht angegeben, so wird die aktuelle Uhrzeit als Ende angenommen. Start ergibt demzufolge sich aus ende - mediaItem.duration. Diese Anfrage ist nur dem User id zugänglich.

/new/user

Fügt einen neuen Nutzer in die DB ein.

Variante: xml/new/user

Beispielanfrage: ~/rest/new/user
POST /mediaTrack/rest/new/userHTTP/1.1
Host: <serveradresse>:<port>
Content-Type: application/json

{"user":{
   "firstName":"Hansi",
   "lastName":"Hinterseer",
   "nick":"hansi",
   "email":"hansi@hinterseer.de",
   "lang":"DE",
   "passwordHash":"tM*3Q+Yv5c/ucjkB",
   "gender":"M",
   "birthdate":1279037277000
}   }

Beachte: Dabei darf nick nicht schon vergeben sein. Auch die email darf nicht im System schon registriert sein. firstName und lastName, passwordHash müssen angegeben werden sowie gender entweder NA oder M oder F als Wert haben. Ist eine dieser Bedingungen nicht erfüllt, so kommt eine entsprechende Fehlermeldung. Der nick des Users darf nicht beliebige Zeichen enthalten: Gültig sind alle Zeichenketten zwischen 3 und 30 Zeichen Länge, die kein '\' oder '/' sowie keinerlei Whitespaces (Leerzeichen, Tab, newLine etc.) enthalten. Die Zeichenkette darf außerdem nicht mit einem Sonderzeichen(außer '_') oder einer Zahl beginnen (Regex: ^[\p{L}_][\p{N}\p{L}\p{P}_]{2,29}$ )

/new/list

Fügt bei einem Nutzer eine neue MediaItem-Liste hinzu. Beachte: Wird eine Liste einem Nutzer hinzugefügt, der schon eine Liste mit diesem Namen hat, so wird die alte Liste durch die neue überschrieben.

Variante: xml/new/list

Parameter Optional [Default] Typ Bemerkung
userId nein long Gibt die id desjenigen Users an, der die MediaListe erstellt.
name nein String Der Name der zu erstellenden Liste
items nein String Eine Liste von durck ':' getrennten Ids der MedienItems, welche in der Liste sein sollen. Die Reihenfolge enstpricht der der Liste.
ordered nein [true] boolean Gibt an, ob die Reihenfolge der Liste ein Rolle spielt oder nicht. (z.B: merkliste vs. Charts..)
token nein String Das Token, welches der anfragende User beim login oder beim Ändern des Passwortes zugesendet bekam.

Beispielanfrage: ~rest/xml/new/list;userId=3;name=test2;items=15:14:13:12:11;token=

Beachte: Diese Methode ist nur dem User id zugänglich.

Manipulieren

/artist/{ id }/update

Aktualisiert den Artist id in der Datenbank.

Parameter Optional [Default] Typ Bemerkung
userId nein long Gibt die id desjenigen MediaItems an, welches aktualisiert werden soll.
uName ja [false] boolean  
uDisambiguation ja [false] boolean  
uBiography ja [false] boolean  
uType ja [false] boolean Mögliche Werte sind: "AUTHOR", "ACTOR", "DIRECTOR", "INTERPRETER", "BAND"
uPic ja [false] boolean  
uBegin ja [false] boolean  
uEnd ja [false] boolean  

Zusätlich zu dem im HTTP-Content gesendeten Objekt müssen noch folgende URL Parameter angeben werden:
Parameter Optional [Default] Typ Bemerkung
userId nein long Gibt die id desjenigen Users an, der das MediaItem hinzufügt.
token nein String Das Token, welches der anfragende User beim login oder beim Ändern des Passwortes zugesendet bekam.

Die boolschen Werte geben jeweils an, ob das entsprechende Attribut übernommen werden soll oder nicht. Damit ist es insesondere auch möglich vorhandene Werte zu löschen, indem z.B. uPic true= ist, und das Attribut picUrl im übergebenen Objekt nicht definiert wurde.

/mediaItem/{ id }/update...

Hinter dieser URL verbergen sich acht weitere URLs, mit denen genauer angegeben wird, welche Art von MediaItem aktualisiert werden soll. All diese Urls haben eine Grundmenge an Parameter gleich, die sie alle angeben können. Darüber hinaus bestizt (fast) jede Url noch eigene weitere Attribute.

Parameter Optional [Default] Typ Bemerkung
id nein long Gibt die id desjenigen MediaItems an, welches aktualisiert werden soll.
uName ja [false] boolean  
uDuration ja [false] boolean  
uChildren ja [false] boolean  
uNext ja [false] boolean  
uArtists ja [false] boolean  
uTags ja [false] boolean  
uPic ja [false] boolean  
uEan ja [false] boolean  
uIsbn ja [false] boolean  
uPublished ja [false] boolean  
uShortDesc ja [false] boolean  
uLongDesc ja [false] boolean  
uSource ja [false] boolean  

Zusätlich zu dem im HTTP-Content gesendeten Objekt müssen noch folgende URL Parameter angeben werden:
Parameter Optional [Default] Typ Bemerkung
id nein long Gibt die id desjenigen Users an, der das MediaItem hinzufügt.
token nein String Das Token, welches der anfragende User beim login oder beim Ändern des Passwortes zugesendet bekam.

Die boolschen Werte geben jeweils an, ob das entsprechende Attribut übernommen werden soll oder nicht. Damit ist es insesondere auch möglich vorhandene Werte zu löschen, indem z.B. uDuration = true ist, und das Attribut duration im übergebenen Objekt nicht definiert wurde.

/mediaItem/{ id }/udpateBook

Zusätzliche Parameter:
Parameter Optional [Default] Typ Bemerkung
uSubtitle ja [false] boolean  
uPage ja [false] boolean  

/mediaItem/{ id }/udpateMovie

Zusätzliche Parameter:
Parameter Optional [Default] Typ Bemerkung
uSubtitle ja [false] boolean  

/mediaItem/{ id }/updateWeb

Zusätzliche Parameter:
Parameter Optional [Default] Typ Bemerkung
uUrl ja [false] boolean  

/mediaItem/{ id }/udpateTv

Zusätzliche Parameter:
Parameter Optional [Default] Typ Bemerkung
uTvType ja [false] boolean  
uSeasonNumber ja [false] boolean  
uEpisodeNumber ja [false] boolean  

/mediaItem/{ id }/udpateGame

Zusätzliche Parameter:
Parameter Optional [Default] Typ Bemerkung
uMinPlayers ja [false] boolean  
uMaxPlayers ja [false] boolean  

/mediaItem/{ id }/udpateVideogame

Zusätzliche Parameter:
Parameter Optional [Default] Typ Bemerkung
uMinPlayers ja [false] boolean  
uMaxPlayers ja [false] boolean  

/mediaItem/{ id }/udpateMusic

Zusätzliche Parameter:
Parameter Optional [Default] Typ Bemerkung
uMusicType ja [false] boolean  

/mediaItem/{ id }/udpatePaper

Zusätzliche Parameter: Keine.

/mediaItem/{ id }/doTag

Tagt das MediaItem mit der Id id ein neues Tag hinzu.

Parameter Optional [Default] Typ Bemerkung
id nein long Gibt die id desjenigen MediaItems an, welches getagged werdn soll.
userId nein long Die id des Users, der das MediaItem tagged
tag nein String Das Tag, welches hinzugefügt werden soll. Existiert es in der Datenbank noch nicht, so wird es neu angelegt. Der Tagname hat bestimmte Einschränkungen, siehe Bemerkung.
token nein String Das Token, welches der anfragende User beim login oder beim Ändern des Passwortes zugesendet bekam.

Beispielanfrage: ~/rest/mediaItem/11/doTag;userId=3;tag=funny;token=

Beachte: Der user muss zum token passen. Der Name des Tags darf nicht beliebige Zeichen enthalten: Gültig sind alle Zeichenketten zwischen 1 und 100 Zeichen Länge, die kein ':', kein '\' oder '/' sowie keinerlei Whitespaces (Leerzeichen, Tab, newLine etc.) enthalten. (Regex: ^[\p{L}\p{N}\p{P}]{1,100}$ )

/user/{ id }/update

Aktualisiert den User mit der Id id aus der Datenbank mit den Daten, die als JSON-Objekt im Content des POST Requests enthalten sind.

Parameter Optional [Default] Typ Bemerkung
id nein Long Wird dieser Parameter angegeben, werden alle anderen ignoriert. In der Ergebnismenge ist nur der User mit der Id id , falls es diesen gibt.
uBirthdate ja [false] boolean Falls true wird das Gebursdatum des gesendeten Users übernommen.
uName ja [false] boolean Falls true wird der Name (First UND Last Name) des gesendeten Users übernommen.
uGender ja [false] boolean Falls true wird das Geschlecht des gesendeten Users übernommen.
uEmail ja [false] boolean Falls true wird die Emai-lAdresse des gesendeten Users übernommen.
uLang ja [false] boolean Falls true wird die bevorzugte Sprache des gesendeten Users übernommen.
uPassword ja [false] boolean Falls true wird das Passwort aktualisiert. Dazu muss das Attribut oldPasswordHash gesetzt sein.
token nein String Das Token, welches der anfragende User beim login oder beim Ändern des Passwortes zugesendet bekam.

Beispielanfrage: ~/rest/user/1/update;uBirthdate=true;uName=true;uGender=true;uLang=false;uPassword=true;token=
POST /mediaTrack/rest/user/1/update;uBirthdate=true;uName=true;uGender=true;uLang=false HTTP/1.1
Host: <serveradresse>:<port>
Content-Type: application/json
Content-Length: 56

{"user":{
   "birthdate":490226400000,
   "gender":"M",
   "id":1,
   "lang":"de",
   "lastName":"Hartmann",
   "firstName":"Jonas der Dritte",
   "oldPasswordHash":"<alterPasswordHash>",
   "passwordHash":"<neuerPasswordHash>"
}   }

Wird folgendes Ergebnis liefern:
{   "response":{"@totalResultCount":"1","@statusCode":"UPDATED","@page":"0","@maxPage":"0",
      "content":{
         "item":{"@type":"xmlToken",
            "expires":1281886866359,
            "user":{
               "birthdate":490226400000,
               "created":1279018752000,
               "firstName":"Jonas der Dritte",
               "gender":"M",
               "id":1,
               "lastName":"Hartmann",
               "lastUpdated":1279019082113,
               "lang":"en",
               "nick":"user1"
            },
            "value":"<tokenValue>"
}   }   }   }
Beachte: Soll ein Attribut gelöscht werden, so muss es mit uAttribut=true in der URL angegeben, sowie das Attribut im Content fehlen. Es wird dann auf null gesetzt. Die Attribute oldPasswordHash und passwordHash werden vom Server aus niemals übertragen. Das zurückgegebene Token enthält den aktualisierten User. Der tokenValue ändert sich nach jedem ;uPassword=true, so dass das bisher genutzte Token ungültig geworden ist! Kann der User nicht aktualisiert werden, so wird kein content mitgesendet ( "content":{"@nil":"true"} ). Diese Methode ist nur dem User id zugänglich.

Löschen

/mediaItem/{ id }/detachChild

Entfernt von dem MediaItem id das untergeordnete MediaItem childId.

Parameter Optional [Default] Typ Bemerkung
id nein long Die Id des MediaItems, von dem das Untergeordnete Element entfernt werden soll.
childId nein long Die Id des Kindes, welches losgelöst werden soll.

Beachte: Das MediaItem childId wird nicht aus der Datenbankentfernt - es existiert weiterhin ohne diese Parent-Child Beziehung.

/delete/historyItem/{ id }

Löscht bei einem Nutzer ein HistoryItem aus seiner History

Parameter Optional [Default] Typ Bemerkung
id nein long Gibt die id des zu löschenden HistoryItems an
token nein String Das Token, welches der anfragende User beim login oder beim Ändern des Passwortes zugesendet bekam.

Beispielanfrage: ~rest/delete/historyItem/342;token=

Beachte: Diese Methode ist nur dem User zugänglich, dem das HistoryItem gehört.

/delete/list

Löscht bei einem Nutzer eine MediaItem-Liste

Variante: xml/delete/list

Parameter Optional [Default] Typ Bemerkung
userId nein long Gibt die id desjenigen Users an, bei dem die Liste gelöscht werden soll.
name nein String Der Name der zu löschenden Liste
token nein String Das Token, welches der anfragende User beim login oder beim Ändern des Passwortes zugesendet bekam.

Beispielanfrage: ~rest/xml/delete/list;userId=3;name=test2;token=

Beachte: Diese Methode ist nur dem User id zugänglich.

Sonstiges

/login

Diese URL bekommt per POST ein UserObjekt, das mindestens das Attribut nick und passwordHash enhalten muss. Es wird dann überprüft, ob diese Kombination valide ist. Diese Methode stellt bei erfolg ein Token zur Verfügung, mit der alle Nutzeraktionen autorisiert werden können.

Beispielanfrage: ~rest/login

POST /mediaTrack/rest/login HTTP/1.1
Host: <serveradresse>:<port>
Content-Type: application/json

{"user":{
   "nick":"hansi",
   "passwordHash":"tM*3Q+Yv5c/ucjkB"
}   }

Wenn das Passwort stimmt, wird folgende Antwort gegeben:
{   "response":{"@totalResultCount":"1","@statusCode":"PASSWORD_ACCEPTED","@page":"0","@maxPage":"0",
      "content":{
         "item":{"@type":"xmlToken",
            "expires":1281886866359,
            "user":{
               "created":1281721957000,
               "firstName":"Hansi",
               "gender":"NA",
               "id":1,
               "lastName":"Hinterseer",
               "lang":"de",
               "nick":"hansi"
            },
            "value":"7ec2972d-d678-4022-ad41-e665a75d15d3"
}   }   }   }
Ist die Anmeldung nicht erfolgreich, lautet der StatusCode: "ILLEGAL_PASS_OR_USER". Die Antwort sieht dann folgendermaßen aus:
{   "response":{"@totalResultCount":"1","@statusCode":"PASSWORD_ACCEPTED","@page":"0","@maxPage":"0",
      "content":{"@nil":"true"}
}   }

Beachte: Das Attribut expires beschreibt den Zeitpunkt, zu dem das Token ungültig wird. Das Attribut value ist das eigentliche Token. Das Token hat eine Gültigkeitsdauer von 24 Stunden. Wird innerhalb dieser 24 Stunden ein erneuts Login durchgeführt, wird die Gültigkeitsdauer des Tokens dementsprechend verlängert, wärend das Token selbst gleich bleibt. Wird nach mehr als 24 Stunden ein Login durchgefürt, erhält man ein neues Token.

/logout/{ id }

Mit dieser Methode wir der User id vom System abgemeldet, bzw sein Token gelöscht.

Parameter Optional [Default] Typ Bemerkung
token nein String Das Token, welches der User beim login zugesendet bekam.

Beachte: Diese Methode ist nur dem User id mit seinem Token zugänglich. Ist das token mittlerweile abgelaufen ist es sinnvoll erneut /login und anschließend /logout/{ id } aufzurufen.

/user/{ id }/requestFriendship

Parameter Optional [Default] Typ Bemerkung
id nein long Gibt den User an, der die Freundschaftsanfrage versendet.
other nein long Gibt die id von dem anderen Partner der Freundschaftsanfrage an.
token nein String Das Token, welches der anfragende User beim login oder beim Ändern des Passwortes zugesendet bekam.

Beachte: Wird eine Freundschaft von User A bei User B angefragt, obwohl User B schon bei User A angefragt hatte und diese Anfrage den Status pending hat, so wird diese Anfrage sofort akzeptiert. Ergebnis der Anfrage hat dann den StatusCode: FRIENDSHIP_ACCEPTED. Diese Methode ist nur dem User id zugänglich.

/user/{ id }/acceptFriendship

Parameter Optional [Default] Typ Bemerkung
id nein long Gibt den User an, der die Freundschaftsanfrage annimmt.
other nein long Gibt die id von denjenigem User an, der die Freundschaftsanfrage versendet hat.
token nein String Das Token, welches der anfragende User beim login oder beim Ändern des Passwortes zugesendet bekam.

Beachte: Diese Methode ist nur dem User id zugänglich.

/user/{ id }/declineFriendship

Parameter Optional [Default] Typ Bemerkung
id nein long Gibt den User an, der die Freundschaftsanfrage aktiv nicht annimmt.
other nein long Gibt die id von denjenigem User an, der die Freundschaftsanfrage versendet hat.
token nein String Das Token, welches der anfragende User beim login oder beim Ändern des Passwortes zugesendet bekam.

Beachte: Diese Methode ist nur dem User id zugänglich.

/user/{ id }/cancelFriendship

Parameter Optional [Default] Typ Bemerkung
id nein long Gibt den User an, der die Freundschaft beendet.
other nein long Gibt die id von dem anderen Partner der Freundschaft an.
token nein String Das Token, welches der anfragende User beim login oder beim Ändern des Passwortes zugesendet bekam.

Beachte: Diese Methode ist nur dem User id zugänglich.

/user/{ id }/withdrawFriendshipRequest

Parameter Optional [Default] Typ Bemerkung
id nein long Gibt den User an, der die Freundschaftsanfrage zurückzieht.
other nein long Gibt die id von dem anderen Partner der Freundschaftsanfrage an.
token nein String Das Token, welches der anfragende User beim login oder beim Ändern des Passwortes zugesendet bekam.

Beachte: Diese Methode ist nur dem User id zugänglich.
Topic revision: r56 - 13 Sep 2010, ChristianBreil
 
This site is powered by FoswikiCopyright © by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding Medieninformatik-Wiki? Send feedback