Unity3D und das Slim Framework

25 Mrz 2014 Posted by: Comments: 0 In: C#, PHP, Programming, Unity3D

Auf der Suche nach einer Möglichkeit eine REST API für eigene Spiele zu erstellen, bin ich über das Slim Framework gestolpert.
Das Framework ist in PHP geschrieben und ermöglich einen recht schnellen Start um solche API´s oder auch andere web applications aufzubauen. Es gibt natürlich einige dieser Frameworks. Slim schien mir jedoch genau das Richtige zu sein – es ist schnell, der Einstieg ist recht leicht und außerdem ist es recht gut dokumentiert.

Zuerst stellt sich natürlich die Frage was ist eine REST API, bzw. REST. Hierbei handelt es sich um eine Architektur, die es ermöglicht API´s mit gut lesbaren URL´s zu erstellen.
Sowas sieht zum Beispiel so aus: http://us.battle.net/api/wow/achievement/485

Dahinter steht meistens eine Datenbankabfrage, die dann wie im Beispiel einen Datensatz im Json Format zurückliefert. Dieser Datensatz kann dann in der eigenen App geparst und anschließend verwendet werden.

Letztlich übernimmt das Framework „nur“ das Routing für diese URL´s, denn eigentlich wird eine index.php angesprochen, diese erscheint wie im Beispiel aber nicht in der URL.

Im Wesentlichen werden dabei vier Befehle benötigt:

  • POST
  • PUT
  • GET
  • DELETE

Es gibt zwar noch mehr dieser Befehle, diese sind aber relativ selten im Gebrauch und werden im Moment vernachlässigt. Einige öffentliche API´s lassen auch nur GET Befehle zu, da die Entwickler natürlich die Daten in der Datenbank nur durch das Spielen des Spiel geändert (POST, PUT, DELETE) werden sollen und nicht durch z.B. Anfragen im Browser. Wie im Beispiel oben dienen diese Schnittstellen dann dazu um z.B. bestimmte Daten anderen web applications zu visualisieren.

 

Der Aufbau

Die gesammte API besteht aus der bereits erwähnten index.php und vielen „Controllern“ für die verschiedenen Datenbankabfragen.

Das Projekt kann dann z.B. so aussehen:

Slim_api

 

Die index.php ist (noch) relativ einfach:

Der erste Test der API kann also so erfolgen während Slim nun anhand der url routet:
http://www.yourdomain.com/api/v1/hello/Hans

Rückgabe wäre dann: „Hello, Hans„! Natürlich ohne Anführungszeichen.

 

Wie sieht es aber aus, wenn ich Daten aus einer Datenbank holen oder in irgendeiner Form modifizieren will?

Gehen wir davon aus, dass wir den Character „Hans“ neu anlegen und seine Daten modifizieren, zurückgeben oder löschen wollen.
Dazu benötigt die index.php diese vier Funktionen BEVOR : $app->run(); ausgeführt wird!

Bei drei dieser Funktionen taucht nun authentication auf.
Slim bietet die Möglichkeit eine Middlelayer einzubauen! Das ist großartig um z.B. durch eine Authentifizierung sicherzustellen, dass der Nutzer diese Aktionen auch ausführen darf.
Der GET-Befehl darf immer ausgeführt werden, da dieser ja nur Daten abruft, aber nicht modifiziert. Kann man machen, muss man natürlich nicht.
Also soweit so gut, damit die API nun die Daten die via PUT über den Body gesendet werden „herausfischen“ kann, benötigt es noch eine Funktion namens verifyRequiredParams.
Diese wird mit den „Feldern“ füttert, die sie filtern soll.
In diesem Fall ist es das Feld „data“. Dahinter verbirgt sich ein json String.
Beide Funktionen werden weiter unten im Text beleuchtet!

Um Nun die Daten von Hans abzurufen sieht die url nun so aus:
http://www.yourdomain.com/api/v1/character/Hans

oder auch mit der id von Hans (angenommen Hans ist bereits eingetragen und hat die id 999):

http://www.yourdomain.com/api/v1/character/999

Gibt man das in die Adresszeile des Browser ein, wird standartmäßig der GET-Befehl ausgeführt und man erhält die Daten von Hans, wenn er in der Datenbank vorhanden ist.

Nicht vergessen: dahinter liegt die index.php!
Die eigentliche URL sieht nämlich so aus:
http://www.yourdomain.com/api/v1/index.php

Direkt neben der index.php liegt eine .htaccess-Datei, die dafür sorgt, dass index.php aus der URL entfernt wird. black magic! 😉

Die .htaccess-Datei sieht so aus:

Um nun die Daten vom Character „Hans“ zu bekommen, braucht es noch den „CharacterController“ und der sieht so aus:

Wie man sieht gibt es eine Klasse namens AbstractController, diese übernimmt den Aufbau der Datenbankverbindung:

und greift dabei auf das connect-Script zu:

die config.php sieht dann so aus:

Die verifyRequiredParams Funktion und die sieht so aus:

Da ich das Feld ‚data‘ übergebe, wird genau danach gesucht. $app->request()->getBody() holt den Body, danach wird geparst und ein paar Checks für das Errorhandling gemacht, für den Fall, dass das Feld ‚data‘ nicht vorhanden ist. Wenn irgendwas mit den Feldern nicht stimmt (nicht vorhanden oder falsch benannt), wird Slim gestoppt: app->stop();

Und was macht nun ‚authentication‘ ? Ein sehr tolles Feature von Slim ist die Möglichkeit Middlelayer einzufügen.
Die Funktion ‚authentication‘ soll überprüfen, ob denn überhaupt Daten verarbeitet werden dürfen, indem das Vorhanden sein von Usernamen und Passwort im Header überprüft wird.

Man sollte sich hier sowieso mit einem „ApiKey“ und Ähnlichem absichern und sowas im Vorfeld prüfen oder besser gleich https nutzen!
Für das Beispiel verzichte ich aber erstmal darauf.

Nun hat man so ziemlich alles zusammen was man benötigt und kann neue Controller erstellen (siehe Abb. oben), diese Controller erben natürlich vom AbstractController und werden automatisch in die index.php geladen.

Von dort aus muss, wie im Beispiel, nur eine Instanz erzeugt werden. Slim übernimmt im Hintergrund die „Magie“ beim Routen, während die Datenbankabfragen vom jeweiligen Controller erledigt wird.

So lässt es sich echt schnell entwicklen! 🙂

 

der Unity3D, bzw. C#-Teil

Jetzt muss das Ganze noch mit Unity verbunden werden. Hierfür nehme ich nicht die Unity-eigene WWW-Klasse. Ich persönlich finde, dass sich Coroutinen für solche Angelegenheiten einfach nur bedingt anbieten und sich dazu unter C# nicht als strings zurückgeben lassen. In diesem Fall heißt der unser Verbündeter „HttpWebRequest“. Der nächste Nachteil der Coroutinen von Unity besteht aus dem Fakt, dass sie nur mit POST und GET arbeiten. Ich benötige aber auch DELETE und PUT. Diese kann man in der „HttpWebRequest.methode“ mitschleifen! Um hier den ein oder anderen Workaround zu vermeiden ist in diesem Fall die „HttpWebRequest“-Klasse der klare Sieger! Auch die WebClient-Klasse tut sich hier schwer. Einziger Nachteil ist bis dato, dass ich System.IO nutzen muss. Dies bedeutet, dass der WebPlayer (vorerst) wegfällt, da dieser aus Sicherheitsgründen in einer Sandbox läuft. Das ist auch gut so. 😉

Holen wir die Daten in das Spiel:

 

 

 

Abschließend muss ich sagen, dass ich nicht einen einzigen Blick in die Slim.php werfen musste – die Doku und ein paar kleine Tests haben völlig ausgereicht um die API auf Slim aufzusetzen.

So soll es sein – funktioniert einfach out of the box! Unity3D, bzw. C# verhielt sich anfangs ein wenig sperriger. Hier war ein wenig die „trial and error“-Methode gefragt.

 

Cheers!

Daniel

Leave a Comment!

Deine E-Mail-Adresse wird nicht veröffentlicht. Erforderliche Felder sind mit * markiert.

Diese Website verwendet Akismet, um Spam zu reduzieren. Erfahre mehr darüber, wie deine Kommentardaten verarbeitet werden.