Vor wenigen Jahren wurden Webapplikation noch so gebaut, dass die Interaktionen mit Datenbank und View unmittelbar von der Applikation selbst durchgef\u00fchrt wurden. Doch mit der steigenden Popularit\u00e4t von mobilen Apps<\/a> und Javascript-Frameworks, etablierten sich zentrale RESTful-APIs als die beste und eleganteste L\u00f6sung, wenn es darum geht, eine einheitliche Schnittstelle zwischen dem jeweiligen Client und dem Datenstamm bereitzustellen.<\/p>\n Bei Laravel handelt es sich um ein in PHP geschriebenes Open-Source-Framework, welches im Jahr 2011 von Taylor Otwell initiiert wurde. Inzwischen erfreut es sich aufgrund seiner Einfachheit und Flexibilit\u00e4t gro\u00dfer Beliebtheit und punktet mit einer weltweit verbreiteten Community.<\/p>\n Der Ausdruck \u201eRESTful API\u201c ist vielen von euch sicherlich ein Begriff. Um darauf n\u00e4her eingehen zu k\u00f6nnen, muss man erstmal verstehen, wof\u00fcr \u201eREST\u201c eigentlich steht, und welche Prinzipien es verfolgt.<\/p>\n REST ist die Abk\u00fcrzung f\u00fcr \u201eRE<\/strong>presentational S<\/strong>tate T<\/strong>ransfer\u201c, und bezeichnet ein Programmierparadigma zur Kommunikation zwischen Applikation \u00fcber ein zustandsloses Protokoll (meistens HTTP). Besonders relevant ist dieses f\u00fcr verteilte Systeme, insbesondere f\u00fcr Webservices.<\/p>\n Bei REST-konformen APIs stellen die Ressourcen die Endpunkte dar. HTTP-Methoden repr\u00e4sentieren die zugeh\u00f6rigen Actions. Es ist genau definiert, bei welcher Zugriffsart welche Aktion ausgel\u00f6st werden soll:<\/p>\n Die HTTP-Methoden HEAD<\/strong>, OPTIONS<\/strong>, CONNECT<\/strong> und TRACE<\/strong> sind optional, und werden f\u00fcr CRUD-Operationen im Normalfall nicht ben\u00f6tigt. Wichtig w\u00e4re es hier auch noch anzumerken, dass eine Eigenimplementierung von CONNECT oder TRACE sich ggf. auf die Sicherheit der Applikation auswirken kann!<\/p>\n Wenn es um die Speicherung von Daten geht, sei es das Neuanlegen oder auch Aktualisieren, teilen sich die Meinungen, ob man daf\u00fcr nun lieber POST, PUT oder auch PATCH (partielles Update) verwenden sollte.<\/p>\n In den folgenden Beispielen wird f\u00fcr das Aktualisieren von Ressourcen auf PUT gesetzt. PUT steht f\u00fcr das Anlegen bzw. Aktualisieren einer Ressource an einem bestimmten Ort.<\/p>\n Was ebenfalls f\u00fcr PUT steht, ist dessen Idempotenz. Das bedeutet, dass wiederholte Anfragen mit den gleichen Daten tats\u00e4chlich nur eine einzige \u00c4nderung bewirken.<\/p>\n Urspr\u00fcnglich sollte dieses Framework lediglich eine bessere Alternative zum bereits beliebten CodeIgniter-Framework<\/a>\u00a0darstellen, da dieses u.a. keine Funktionen betreffend Authentifizierung mitbrachte.<\/p>\n Mit der Zeit wurde dessen Funktionsumfang in gro\u00dfem Ma\u00dfe erweitert, und brachte neben der Unterst\u00fctzung von Dependency Injections auch eine eigene Template-Engine (\u201eBlade\u201c) mit.<\/p>\n Im Jahr 2012 erfolgte dann mit dem mitgelieferten Command-Line-Tool \u201eArtisan\u201c ein weiterer gro\u00dfer Durchbruch, da dieses es erm\u00f6glicht, s\u00e4mtliche Interaktionen mit dem Framework unmittelbar \u00fcber die Konsole auszuf\u00fchren. Des Weiteren folgte auch eine Unterst\u00fctzung f\u00fcr eine noch breitere Palette an Datenbanksystemen.<\/p>\n Als das Laravel-Framework mit Version 4 dann vollst\u00e4ndig \u00fcber Composer geladen und verwaltet werden konnte, stieg auch dessen Erweiterbarkeit entsprechend an, was dem Entwickler noch mehr Freiheiten einr\u00e4umte.<\/p>\n Weitere Informationen diesbez\u00fcglich k\u00f6nnen direkt auf der Homepage<\/a> des Frameworks eingesehen werden.<\/p>\n F\u00fcr die folgenden Beispiele gehen wir davon aus, dass das Laravel-Framework bereits installiert und lauff\u00e4hig ist. Ob dies nun via Homestead<\/a>, Composer oder auch einer manuellen Installation eines ver\u00f6ffentlichten Releases von GitHub erfolgt, spielt hier keine Rolle. Des Weiteren sollte auch die Datenbankverbindung bereits konfiguriert und funktionsf\u00e4hig sein.<\/p>\n Wir treffen die Annahme, dass f\u00fcr das folgende Beispiel der Model-Name ident zum Ressourcen-Namen ist. Dies ist keine zwingend erforderliche Ma\u00dfnahme, f\u00f6rdert jedoch die Nachvollziehbarkeit ungemein.<\/p>\n Als Ressource werden wir hier eine \u201eNotiz\u201c (engl. \u201eNote\u201c) anlegen, welche einen Titel (\u201eSubject\u201c) sowie einen Textk\u00f6rper (\u201eBody\u201c) hat.<\/p>\n Beginnen wir nun als Erstes damit, das Model inkl. Migration mit Hilfe des von Laravel mitgelieferten Command-Line-Tools \u201eArtisan<\/a>\u201c zu erstellen.<\/p>\n Dazu navigieren wir mit dem Terminal (Linux) bzw. der Eingabeaufforderung (Windows) direkt in das Projektverzeichnis und geben dabei den folgenden Command ein:<\/p>\n php artisan make:model Note -m<\/strong><\/p>\n Mit diesem Command wird ein neues Model namens \u201eNote\u201c erstellt. Der optionale Paramter \u201e-m\u201c gibt an, dass parallel dazu eine entsprechende Migration angelegt wird. Das soeben generierte Model liegt unter .\/app\/Note.php<\/strong>, die zugeh\u00f6rige Migration unter .\/database\/migrations\/YYYY_MM_DD_XXXXXX_create_notes_table.php<\/strong>.<\/p>\n Sehen wir uns nun zun\u00e4chst mal die Migration an.<\/p>\n Die up()<\/strong> und down()<\/strong>-Methoden dienen der Durchf\u00fchrung der Migration bzw. deren Rollback.<\/p>\n Mit $table->increments(‚id‘)<\/strong> wird festgelegt, dass hierf\u00fcr ein INT-Feld mit Auto-Increment als Primary-Key erzeugt wird. Die Anweisung $table->timestamps()<\/strong> sorgt daf\u00fcr, dass zus\u00e4tzlich die von Laravel verwalteten Felder \u201ecreated_at\u201c und \u201eupdated_at\u201c ebenfalls erzeugt werden. Ob diese nun genutzt werden sollen oder nicht, l\u00e4sst sich \u00fcbrigens auch direkt im Model konfigurieren, aber standardm\u00e4\u00dfig werden diese verwendet.<\/p>\n F\u00fcgen wir der zuvor generierten Migration nun unsere beiden Felder \u201eSubject\u201c und \u201eBody\u201c hinzu, sodass die up()<\/strong>-Methode dann schlie\u00dflich wie folgt aussieht:<\/p>\n F\u00fchren wir nun die Migration mit dem folgenden Command aus:<\/p>\n php artisan migrate<\/strong><\/p>\n Sollte es m\u00f6glicherweise zu einem Fehler wie \u201eSpecified key was too long error<\/em><\/strong>\u201c kommen, k\u00f6nnte die folgende Ma\u00dfnahme helfen.<\/p>\n Dazu erweitern wir den App-Service-Provider unter .\/app\/Providers\/AppServiceProvider.php<\/strong> wie folgt und wiederholen anschlie\u00dfend den vorigen Schritt:<\/p>\n Widmen wir uns nun jedoch wieder unserem \u201eNote\u201c-Model. Diesem f\u00fcgen wir nun das \u201eprotected\u201c-Attribut \u201efillable\u201c hinzu, und legen fest, welche Felder davon in der Datenbank bef\u00fcllt werden d\u00fcrfen.<\/p>\n Unter dem Begriff Datenbank-Seeding versteht man das Bef\u00fcllen einer Datenbank bzw. einer Datenbank-Tabelle (bei relationalen Systemen) mit Testdaten. Diese werden dabei i.d.R. dynamisch nach dem Zufallsprinzip erzeugt.<\/p>\n Erstellen wir mit dem folgenden Command nun eine Seeder-Klasse, welche unsere Notes-Tabelle mit Testdaten bef\u00fcllen wird:<\/p>\n php artisan make:seeder NotesSeeder<\/strong><\/p>\n Nun \u00f6ffnen wir die soeben erzeugte Seeder-Klasse unter .\/database\/seeds\/NotesSeeder.php<\/strong> und f\u00fcgen hier Folgendes ein:<\/p>\n Die Faker-Klasse erm\u00f6glicht die Generierung von zuf\u00e4lligen Pseudo-Inhalten, selektierbar nach Typ. Hier wird als erstes die Datenbank-Tabelle geleert, sodass wir mit jeder Ausf\u00fchrung dieses Seeders wieder von Neuem starten k\u00f6nnen. In einer Schleife werden nun 200 zuf\u00e4llige Eintr\u00e4ge generiert und gespeichert. Um den Seeder nun auszuf\u00fchren, machen wir uns wieder Artisan zunutze:<\/p>\n php artisan db:seed –class=NotesSeeder<\/strong><\/p>\n Sollten wir mehrere Seeder-Klassen haben, w\u00e4re es einfacher, diese dem zentralen \u201eDatabase-Seeder\u201c hinzuzuf\u00fcgen, indem wir die einzelnen, von uns erstellten Seeder-Klassen in der run()<\/strong>-Methode der DatabaseSeeder()<\/strong>-Klasse im gleichen Verzeichnis registrieren.<\/p>\n Nun k\u00f6nnen wir mit dem Artisan-Seed-Command ohne spezifische Angabe einer Klasse alle im DatabaseSeeder()<\/strong> registrierten Seeder ausf\u00fchren.<\/p>\n php artisan db:seed<\/strong><\/p>\n Damit wir mit den Daten interagieren k\u00f6nnen, bedarf es eines Controllers, welcher die Kommunikation zwischen Client und Datenbank \u00fcbernimmt. In diesem Fall ben\u00f6tigen wir jedoch einen sogenannten Resource-Controller, d.h. er muss mindestens die folgenden Actions implementieren:\u00a0 index()<\/strong>, store()<\/strong>, update()<\/strong> und destroy()<\/strong>. Dazu nutzen wir ebenfalls wieder Artisan:<\/p>\n php artisan make:controller NotesController<\/strong><\/p>\n Der neu erstellte NotesController()<\/strong> befindet sich unter .\/app\/Http\/Controllers\/NotesController.php<\/strong>. In diesem legen wir nun die vorhin genannten Actions an, und implementieren das Basis-Verhalten.<\/p>\n Bei mehreren Resource-Controllern w\u00fcrde es Sinn machen, daf\u00fcr einen Basis-Resource-Controller anzulegen, und die jeweiligen Resource-Controller davon erben zu lassen. Das\u00a0hat den Vorteil, das Basisverhalten in jedem Controller nutzen zu k\u00f6nnen und bringt gleichzeitig auch die M\u00f6glichkeit, f\u00fcr einzelne Controller bestimmte Actions zu \u00fcberschreiben.<\/p>\n Nachdem nun das CRUD-Verhalten grunds\u00e4tzlich implementiert ist, m\u00fcssen nur noch die Routen definiert werden. Dazu \u00f6ffnen wir die Datei .\/routes\/api.php<\/strong> und f\u00fcgen dort die folgende Zeile ein:<\/p>\n Die Routen-Konfiguration von Laravel erlaubt es auf diese Art einen Endpunkt direkt auf einen Resource-Controller<\/a>\u00a0zu routen. Laravel hat hierf\u00fcr bereits bestimmte Actions beim jeweiligen Controller f\u00fcr sich reserviert. Dabei handelt es sich um jene, die wir bereits zuvor beim NotesController()<\/strong> angelegt haben. Die folgende Tabelle soll Aufschluss geben wie die URL-Struktur f\u00fcr einen solchen Resource-Controller aussieht, und welche Action hinter welcher HTTP-Methode liegt.<\/p>\nREST \u2013 Was sich dahinter verbirgt<\/h2>\n
HTTP-Methoden definieren Actions<\/h3>\n
\n
\n<\/strong>L\u00e4dt Informationen der gew\u00fcnschten Ressource vom Server, und verursacht dabei keine Nebeneffekte. GET-Requests m\u00fcssen laut Spezifikation \u201esicher\u201c sein, d.h. ein Request darf keine Auswirkungen auf die Ressource haben. Das Verhalten wird als nullipotent bezeichnet.<\/li>\n
\nLegt im jeweiligen Ressourcenstamm anhand der \u00fcbermittelten Daten eine neue Ressource an. Erstellt mit jedem weiteren Aufruf neue Ressourcen, statt die \u00e4quivalente wieder zur\u00fcckzugeben. Dieses Verhalten wird als nicht idempotent bezeichnet.<\/li>\n
\nAktualisiert mit den \u00fcbermittelten Daten eine bereits bestehende Ressource. Weitere Aufrufe verursachen keine weiteren Nebeneffekte. Im Gegensatz zu POST wird dieses Verhalten hier als idempotent bezeichnet.<\/li>\n
\n<\/strong>L\u00f6scht die geforderte Ressource, und ist vom Verhalten her analog zu PUT ebenfalls idempotent.<\/li>\n<\/ul>\nDaten speichern: POST vs. PUT<\/h3>\n
REST-Integration in Laravel<\/h2>\n
Erstellen einer Ressource<\/h2>\n
<?php\r\n\r\nuse Illuminate\\Support\\Facades\\Schema;\r\nuse Illuminate\\Database\\Schema\\Blueprint;\r\nuse Illuminate\\Database\\Migrations\\Migration;\r\n\r\nclass CreateNotesTable extends Migration\r\n{\r\n \/**\r\n * Run the migrations.\r\n *\r\n * @return void\r\n *\/\r\n public function up()\r\n {\r\n Schema::create('notes', function (Blueprint $table) {\r\n $table->increments('id');\r\n $table->timestamps();\r\n });\r\n }\r\n\r\n \/**\r\n * Reverse the migrations.\r\n *\r\n * @return void\r\n *\/\r\n public function down()\r\n {\r\n Schema::dropIfExists('notes');\r\n }\r\n}<\/pre>\npublic function up()\r\n{\r\n\tSchema::create('notes', function (Blueprint $table) {\r\n\t\t$table->increments('id');\r\n\t\t$table->string('subject');\r\n\t\t$table->text('body');\r\n\t\t$table->timestamps();\r\n\t});\r\n}<\/pre>\nuse Illuminate\\Support\\Facades\\Schema;\r\n\r\npublic function boot()\r\n{\r\n\tSchema::defaultStringLength(191);\r\n}<\/pre>\n<?php\r\n\r\nnamespace App;\r\n\r\nuse Illuminate\\Database\\Eloquent\\Model;\r\n\r\nclass Note extends Model\r\n{\r\n\r\n\t\/**\r\n\t * @var array\r\n\t *\/\r\n\tprotected $fillable = ['subject', 'body'];\r\n}<\/pre>\nDatenbank-Seeding<\/h2>\n
<?php\r\n\r\nuse Illuminate\\Database\\Seeder;\r\nuse App\\Note;\r\n\r\nclass NotesSeeder extends Seeder\r\n{\r\n\t\/**\r\n\t * Run the database seeds.\r\n\t *\r\n\t * @return void\r\n\t *\/\r\n\tpublic function run()\r\n\t{\r\n\t\t\/\/ truncate already existing data\r\n\t\tNote::truncate();\r\n\r\n\t\t\/\/ make instance of the Faker-class\r\n\t\t$faker = \\Faker\\Factory::create();\r\n\r\n\t\t\/\/ insert some random generated records\r\n\t\tfor ($i = 0; $i < 200; $i++) {\r\n\t\t\tNote::create([\r\n\t\t\t\t'subject' => $faker->sentence(),\r\n\t\t\t\t'body' => $faker->paragraph(),\r\n\t\t\t]);\r\n\t\t}\r\n\t}\r\n}<\/pre>\n<?php\r\n\r\nuse Illuminate\\Database\\Seeder;\r\n\r\nclass DatabaseSeeder extends Seeder\r\n{\r\n\t\/**\r\n\t * Run the database seeds.\r\n\t *\r\n\t * @return void\r\n\t *\/\r\n\tpublic function run()\r\n\t{\r\n\t\t$this->call( NotesSeeder::class );\r\n\t}\r\n}<\/pre>\nResource-Controller anlegen<\/h2>\n
<?php\r\n\r\nnamespace App\\Http\\Controllers;\r\n\r\nuse Illuminate\\Http\\Request;\r\nuse App\\Note;\r\n\r\nclass NotesController extends Controller\r\n{\r\n\t\/**\r\n\t * Index function for general listing.\r\n\t *\r\n\t * @param Request $request\r\n\t *\r\n\t * @return \\Illuminate\\Http\\JsonResponse\r\n\t *\/\r\n\tpublic function index(Request $request)\r\n\t{\r\n\t\t$notes = Note::all();\r\n\r\n\t\treturn response()->json($notes);\r\n\t}\r\n\r\n\r\n\t\/**\r\n\t * Store-Action\r\n\t *\r\n\t * @param Request $request\r\n\t *\r\n\t * @return \\Illuminate\\Http\\JsonResponse\r\n\t *\/\r\n\tpublic function store(Request $request)\r\n\t{\r\n\t\t$note = Note::create($request->all());\r\n\r\n\t\treturn response()->json($note);\r\n\t}\r\n\r\n\r\n\t\/**\r\n\t * Show-Action\r\n\t *\r\n\t * @param Request $request\r\n\t * @param int $id\r\n\t *\r\n\t * @return \\Illuminate\\Http\\JsonResponse\r\n\t *\/\r\n\tpublic function show(Request $request, $id)\r\n\t{\r\n\t\t$note = Note::find($id);\r\n\r\n\t\treturn response()->json($note);\r\n\t}\r\n\r\n\r\n\t\/**\r\n\t * Update-Action\r\n\t *\r\n\t * @param Request $request\r\n\t * @param int $id\r\n\t *\r\n\t * @return \\Illuminate\\Http\\JsonResponse\r\n\t *\/\r\n\tpublic function update(Request $request, $id)\r\n\t{\r\n\t\t$note = Note::findOrFail($id);\r\n\t\t$note->update($request->all());\r\n\r\n\t\treturn response()->json($note);\r\n\r\n\r\n\t}\r\n\r\n\r\n\t\/**\r\n\t * Destroy-Action\r\n\t *\r\n\t * @param Request $request\r\n\t * @param int $id\r\n\t *\r\n\t * @return \\Illuminate\\Http\\JsonResponse\r\n\t *\/\r\n\tpublic function destroy(Request $request, $id)\r\n\t{\r\n\t\tNote::find($id)->delete();\r\n\r\n\t\treturn response()->json([], 204);\r\n\t}\r\n}<\/pre>\nAPI-Routen registrieren<\/h2>\n
Route::resource('notes', 'NotesController');<\/pre>\n