Wenn euch das Ganze zu viel Text ist, hier der Link zur auf 3 A4 Seiten komprimierten englischen Variante auf meinem Google Drive: link
Seid jedoch gewarnt: Das ist sehr unübersichtlich ohne nachfolgende Infos 😉

Plex? Was ist das?

Plex ist einfach gesagt ein MediaServer um seine Filme, TvSerien und Musik einfach verwalten und von überall aus darauf zugreifen zu können. Hierzu lädt man einfach den Plex Media Server herunter und fügt im sehr intuitiven WebUI seine Media Libraries hinzu. Plex erkennt dann automatisch mithilfe diverser Media Datenbanken und dem Titel der File, um was für einen Film oder was für eine Serie es sich handelt. Im Hintergrund werden dann die Metadaten dieser Inhalte heruntergeladen um euch die Filme Annehmlich präsentieren zu können:

Wird dann ein Film ausgewählt, sieht man die Details zum Film:

Das schöne daran; es funktioniert alles automatisch, sofern man die Filmdatei halbwegs richtig benannt hat.

Um die Filme nun abspielen zu können gibt es mehrere Varianten:
Zum einen gibt es eine App für Android und iOS welche jedoch ein wenig Kostet (5CHF oder so…).
Andererseits kann man jedoch auch bequem von jedem Gerät, welches einen halbwegs anständigen WebBrowser mitbringt, seine Filme via WebUI anschauen.
Wa Plex nun jedoch sehr interessant macht; es gibt diese Apps auch für Smart TVs, Konsolen der neueren Generationen (à la XBox One, PS4) und auch dem PC wenn man denn einen Home Theatre PC hat.

Für mehr Infos zu Plex: plex.tv

 

Schön und gut.. Aber was ist mit der API?

Nun, Plex ist nicht so offen was ihre Schnittstellen und deren Ansprechung anbelangt. Wahrscheinlich wollen sie keine third Party Apps welche auf ihre Produkte zugreifen können. Doch das hält uns doch nicht auf! Oder?

Wichtigstes zu erst:

  • Die Plex Web API ist kein bisschen öffentlich Dokumentiert! Wahrscheinlich eben aus oben genannten Gründen.
  • Es ist eine RESTful API
  • Output der Requests: XML

Als ich mich für mein Projekt auf die Suche nach Informationen gemacht habe, kam ich ziemlich schnell auf eine Gruppe von Personen welche die WebAPI auseinandergenommen haben und ihre Resultate auf Github zur verfügung gestellt haben: github link

Problem: das Ganze ist nicht sehr verständlich geschrieben, es fehlen einige Infos oder einige sind schlichtweg falsch. Wahrscheinlich weil Plex selber immer wieder Änderungen an der eigenen API vornimmt. Und da sie auch keine Rücksicht auf Drittentwickler nehmen müssen, können diese Änderungen auch etwas gravierender ausfallen.

Ein weiterer Punkt welcher bei der Verwendung dieser API für Selbstzwecke im Hinterkopf behalten werden muss!

Um euch, und mir selber ;-), die Verwendung dieser API ein wenig einfacher zu Gestalten, habe ich das Ganze selber zusammengefasst und fehlende oder falsche Infos durch Analyse der Kommunikation zwischen den Produkten durch richtige Informationen ersetzt:

 

Fertig gelabert! Harte Fakten sind gefragt…

Ein Request an die Plex Web API ist grundsätzlich immer gleich aufgebaut. Doch bevor wir damit beginnen eine kleine Warnung: Die Reihenfolge der Parameter in der URL ist strikt einzuhalten! Man kann die Parameter nicht, wie man es vielleicht aus anderen APIs wie der „the Movie Database“ API gewohnt ist, zusammenwürfeln wie man gerne möchte. Andernfalls ist ein „Bad Request“ garantiert!

Der Aufbau des Requests besteht im Grundsatz aus drei Teilen:

  • Base URL -> Adresse und Port des Servers
  • Request URL -> was ihr vom Server wollt
  • Request Header -> Infos für den Server über euch (im mindesten der AuthToken!)

Base URL:

Wie oben erwähnt, bestehend aus Adresse und Port. Wie ihr die Adresse herausfindet wisst ihr sicher und sonst fragt euren lieben Freund Google 😉 . Den Port könnt ihr in den Einstellungen zum Plex Server einstellen. Standart Port ist 32400. Wenn ihr nicht wisst wie das geht, Google weiss es. Denkt an die Portweiterleitung. Keine Ahnung? -> Google hilft gerne.

Ein Beispiel wie so eine Adresse aussieht: https://mydomain.ch:32400/ oder https://212.25.0.232:32400

Request URL:

Nun wird es richtig Interessant. Die Request URL ist das Herz eurer Anfrage an den Server und definiert genau was ihr von wo haben möchtet. Um das Ganze zu vereinfachen, eine kleine Tabelle:

Request Headers:

Wo es vorher Interessant wurde, wird es jetzt mühselig. Oder simpel, je nachdem was für Anforderungen man stellt.
Im simpelsten Fall besteht der Request Header nämlich nur aus dem Plex Authentification Token -> „X-Plex-Token“. Im schlimmsten Falle aus Aneinanderreihungen von X-Plex Infos für den Server.

Hier gehe ich nur auf den AuthToken vertieft ein, da er der einzige Header ist welchen man zwingend benötigt.

Der AuthToken wird benötigt, damit der Server euren User identifizieren kann, und somit weiss, ob ihr berechtigt seid, diese Anfrage zu stellen. Der wichtigste Punkt hierbei, und mit wichtig meine ich ultimativ wichtig!: Der AuthToken muss vom Admin User stammen und was noch viel wichtiger ist: der AuthToken eines Users ändert sich, wenn ein der User sein Passwort ändert! Das heisst der Token ist nicht an den Usernamen, sondern an das User Passwort gebunden!

Um nun euren Token herauszufinden, habe ich euch eine kleine Hilfe zusammengestellt:
Logt euch im Web Interface als Admin ein.
Klickt auf die drei kleinen Pünktchen bei einem Film oder so:

Klickt auf View XML:

Nun seht ihr euren Token in der URL:

 

Für die restlichen X-Plex Headers habe ich eich die Tabelle aus dem Github reinkopiert:

 

Uff… Und was ist nun der Output des Ganzen?

Nunja, immer eine riesige unübersichtliche XML (mal abgesehen vom Image Request). Diese XML sieh in etwa so aus:

Darin findet ihr sämtliche Informationen zu eurer Anfrage.
Die Infos für einen einzigen Film aus obiger Anfrage:

Um das Deserializing dürft ihr euch nun selber kümmern 😉 .

Bei weiteren Fragen zu Plex Web API könnt ihr mir genre im Hangouts schreiben!

Und nun: have Fun!