
GraphQL – Die Alternative zu REST
Teil 1: Übersicht und Backend
Was ist GraphQL?
GraphQL ist eine Abfragesprache für APIs zur Ausführung von Abfragen mit Hilfe eines für die Daten definierten Typensystems. GraphQL ist nicht an eine bestimmte Datenbank gebunden (https://graphql.org/learn/)
GraphQL vs. REST
GraphQL bietet die Möglichkeit, Daten über HTTP zu senden. Jede Anfrage in GraphQL ist eine POST-Anfrage. Der Body enthält die Abfrage für den Server, welcher die Abfrage auflöst. Um Daten zu erhalten, wird eine Query gesendet. Wenn man Daten erstellen, ändern oder löschen möchte, wird eine Mutation gesendet.
GraphQL ist eine flexible Abfragesprache für APIs. Es ermöglicht Entwicklern, genau die Daten zu erhalten, die sie benötigen.
Vor- und Nachteile von GraphQL
Pro:
Schnelle Prototypenentwicklung
API-Erweiterung ohne Versionierung
Autogenerierte API-Dokumentation mit GraphiQL
Es werden immer die Daten geholt, die benötigt werden
Loose coupling zwischen Server und Client
Contra:
Keine simple Caching-Strategie
Overkill für kleine Anwendungen
File-Upload nicht möglich
Komplex beim Einstieg
Performanceprobleme bei tief verschachtelten Abfragen
GraphQL 101
In dieser kleinen Blog-Serie schauen wir uns einfache Queries und Mutations an. Wir haben eine kleine Testanwendung mit Adressen und Benutzern, diese stehen in einer 1-zu-1 Beziehung zueinander. Die Anwendung wurde mit folgender Technologie umgesetzt:
.NET Core 2.2
Entity Framework Core
GraphQL for .NET (https://graphql-dotnet.github.io/)
GraphiQL (https://github.com/graphql/graphiql)
Angular
Query
Die einfachste Art eine Query zu beschreiben ist es, diese mit einem GET-Request à la REST zu vergleichen.

Abbildung 1: eine einfache Query in GraphiQL
Mit dieser einfachen Query wird ein User mit den Eigenschaften firstName und lastName geladen. Hier sieht man bereits den Vorteil von GraphQL, dass das Ergebnis den gleichen Aufbau aufweist wie die Abfrage. Außerdem haben wir nur die Daten erhalten, die wir auch abgefragt haben.

Abbildung 2: User und Address Klasse mit Eigenschaften
Die Entität User hat mehr Eigenschaften als nur firstName und lastName:

Abbildung 3: Datenabfrage eines Users mit einer spezifischen Id
In Abbildung 3 haben wir ein Beispiel einer Query mit einem Argument.
user(id:25)
user = Name der Query
id = Name des Arguments
25 = Wert des Arguments
In GraphQL spricht man nicht von Parametern, sondern von Argumenten.
Außerdem zeigt dieses Beispiel die verschachtelte Abfrage der Address-Eigenschaften.
Mutation
Eine Mutation ist eine Unterart der Query. Damit werden, wie der Name schon vermuten lässt, Daten erstellt, geändert oder gelöscht.

Abbildung 4: Beispiel Mutation mit zwei Argumenten und dem Rückgabewert Id
In diesem Beispiel können wir eine weitere Eigenschaft von GraphQL Queries sehen: query variables. Darin werden komplexe Objekte eingetragen; in unserem Beispiel ein User und eine Address.
Jede Mutation beginnt mit dem Wort mutation,um diese Query als eine Mutation zu erkennen. Der Inhalt in der Klammer definiert Variablen und den entsprechenden Datentypen dazu. In unserem Beispiel entspricht die Variable $user einem UserInput.

Abbildung 5: UserInputType
Unsere UserInputType Klasse erbt von InputObjectGraphType<T> wobei T in unserem Beispiel die Entität User ist. Der Name entspricht dem Namen in Abbildung 4. Standardmäßig akzeptieren die Felder keine NULL-Werte. Mit einem false als zweiten Parameter, akzeptieren die Felder auch ein NULL als Wert.

Abbildung 6: Nullable Field
Datentypen in GraphQL, GraphQL for .NET und .NET
Ein GraphQL-Objekttyp hat einen Namen und Felder, aber irgendwann müssen diese Felder in konkrete Daten umgewandelt werden. An dieser Stelle kommen die skalaren Typen ins Spiel.
In der Abbildung 7 sieht man die Typen, die von der GraphQL Specificiation bereitgestellt werden. Außerdem können wie im UserTypeInput-Beispiel eigene Typen erstellt werden.
Abbildung 7: Skalare Typen

Backend Struktur
Das Beispielprojekt ist in zwei Projekte aufgeteilt (das Testprojekt wird ignoriert). Das Data-Projekt enthält die Logik zum Lesen und Schreiben von Daten in die Datenbank mit Entity Framework. Das API-Projekt beinhaltet die interessante GraphQL-Logik. Aus Gründen der Einfachheit werden wir auch das Data-Projekt ignorieren.
Abbildung 8: Projekt Struktur
Wir legen den Fokus auf folgende Klassen:
GraphQuery
AppSchema
AppQuery
AppMutation
UserType und AddressType
UserInputType und AddressInputType
ContextServiceLocator
GraphQlController

GraphQuery.cs
Die GraphQuery Klasse beinhaltet die Definition, welche Eigenschaften eine Query haben kann.

Abbildung 9: GraphQuery.cs
In unserem Beispiel hat unsere Klasse zwei Eigenschaften:
Query – die Query selbst
Variables – die Variablen, die mit der Query mitgesendet werden
AppSchema
Das AppSchema beschreibt die möglichen Queries und Mutations. Außerdem löst der IDependencyResolver, eine Komponente der GraphQL for .NET Library, die Abhängigkeiten auf.

Abbildung 10: AppSchema
AppQuery
Diese Klasse enthält die Definitionen darüber, wie die Daten abgefragt werden können. Eine GraphQL Query wird als Field bezeichnet. Jedes Field ist einem Typen zugeordnet und hat folgende Parameter:
name : String – der Name der Query
arguments : QueryArguments – Liste mit Argumenten vom Typ QueryArgument<T>, wobei T ein ObjectGraphType ist
resolve : ResolveContextField – hier wird definiert, was getan werden muss, um die Daten zu bekommen. Außerdem muss hier ein dem Field entsprechender Rückgabewert definiert werden

Abbildung 11: AppQuery
AppMutation
Eine Mutation ist genauso aufgebaut wie eine Query, mit der Ausnahme, dass die Eigenschaft Name gesetzt werden muss.

Abbildung 12: Ausschnitt Mutation
UserType und AddressType
Diese Klassen erben von der Klasse ObjectGraphType. Dadurch können Objekte dieser Klasse in Feldern von Queries und Mutations vorkommen. In unserem Beispiel erben wir von einer konkreteren Klasse, und zwar ObjectGraphType<T>, wobei T einmal User und einmal Address ist. Dadurch können wir die Field-Eigenschaft einfacher mit den Eigenschaften der entsprechenden Entität zusammenführen. Standardmäßig werden hier keine NULL-Werte erlaubt. Mit dem optionalen Parameter true als zweiten Übergabeparameter kann man dennoch NULL-Werte zulassen. Durch einen Namen kann der Type einfacher in der GUI von GraphiQL erkannt werden.

Abbildung 13: Eigene Definitionen von ObjectGraphType
UserInputType und AddressInputType
Um Mutations mit ganzen Objekten zu erstellen, werden InputTypes benötigt. Die Klassen der InputTypes erben von InputObjectGraphType<T>. Auch hier kann T wieder einer Entität entsprechen, um die Eigenschaften einfacher zu definieren.

Abbildung 14: UserInput- und AddressInputType
ContextServiceLocator
Diese praktische Klasse dient als Hilfe für unsere AppQuery und AppMutation-Klasse, um die entsprechenden Repositories zu laden.

Abbildung 15: ContextServiceLocator
GraphQlController
Für eine GraphQL Anwendung wird nur ein Controller benötigt. Das heißt natürlich nicht, dass man nicht mehrere Controller verwenden darf. Bei mehreren AppSchema Klassen kann es sehr nützlich sein, auch mehrere Controller zu haben. Durch constructor dependency injection wird das AppSchema und die Komponente IDocumentExecuter bereitgestellt. Der IDocumentExecuter ruft die entsprechende Query oder Mutation auf.

Abbildung 16: GraphQLController
Fazit
GraphQL ist der Traum jedes Frontend-Entwicklers. Keine Daten fehlen in der Anfrage und es werden auch nicht zu viele gesendet. Leider wird in diesem Beispiel das sogenannte “under/overfetching”-Problem nach hinten verschoben, zwischen Backend und Datenbank, da Entity Framework alle Eigenschaften mit lädt. Das Gerüst zu bauen – mit allen Queries und Mutations – kann durchaus mehr Zeit in Anspruch nehmen, als vielleicht zuerst erwartet. Wenn diese initiale Arbeit aber erstmal geleistet worden ist, ist es sehr effizient an einer GraphQL Anwendung zu arbeiten. Wenn am Datenmodel nicht mehr gearbeitet wird, kann jeder Frontend-Entwickler sich die Daten so holen, wie es für seine Plattform am besten ist.






