Eine API verbindet Anwendungen über einen vereinbarten Datenvertrag. Bevor Sie zwischen REST und GraphQL wählen, bestimmen Sie die Clients, ihre benötigten Daten und die erlaubten Operationen. Eine Schnittstelle muss auch Fehler, Zugriffsschutz und Änderungen am Vertrag verständlich behandeln.
REST: Ressourcen und HTTP-Verhalten
Bei einer REST-orientierten API beschreiben URLs Ressourcen, während HTTP-Methoden die jeweiligen Operationen ausdrücken. Planen Sie die Bedeutung von Lesen, Anlegen, Ändern und Löschen konsistent. Statuscodes und Fehlerantworten müssen zum tatsächlichen Ergebnis passen.
Ein Client sollte erkennen können, welche Felder eine Antwort enthält und wie er größere Bestände durchläuft. Eine stabile Sortierung und eine passende Pagination sind dafür ebenso wichtig wie verständliche Namen. Prüfen Sie außerdem, welche Operationen gefahrlos wiederholt werden können und wann ein Schutz vor doppelten Änderungen nötig ist.
GraphQL: Schema und angeforderte Felder
GraphQL beschreibt den Datenvertrag über ein Schema. Der Client wählt daraus die Felder, die er benötigt. Das kann bei unterschiedlichen Clients nützlich sein; die serverseitige Datenbeschaffung und die Zugriffsprüfung bleiben jedoch Aufgaben der Anwendung.
Eine flexible Abfrage kann auf dem Server viel Arbeit auslösen. Legen Sie deshalb Regeln für Abfragekosten und Ergebnismengen fest. Prüfen Sie den Zugriff auf Objekte und einzelne Felder. Ein zentraler Endpunkt vereinfacht diese Berechtigungen nicht automatisch.
Die Entscheidung mit konkreten Clients prüfen
Vergleichen Sie typische Abrufe und Änderungen. Wie viele Aufrufe sind nötig? Welche Daten werden übertragen? Wie verhalten sich Caching, Fehlersuche und Erweiterungen? Diese Fragen sind hilfreicher als eine pauschale Aussage, ein Ansatz sei moderner oder schneller.
Beide Ansätze benötigen dokumentierte Regeln für Authentifizierung, Berechtigungen und Eingaben. Legen Sie Tests für erlaubte und unerlaubte Zugriffe an. Bewerten Sie dabei auch die Betriebsaufgaben: Überwachung, begrenzte Last und die Pflege des Datenvertrags.
Änderungen für bestehende Clients planbar machen
Eine zusätzliche Ausgabe oder ein geändertes Pflichtfeld kann bestehende Clients beeinflussen. Prüfen Sie Änderungen gegen deren Anforderungen und dokumentieren Sie Übergänge. Ein kleines getestetes API-Beispiel ist eine gute Grundlage; daraus folgt keine allgemeine Zusage über Sicherheit oder Skalierung.
Weiterführende Dokumentation: GraphQL: Grundlagen.
Weiterführende Dokumentation: Django REST Framework: Berechtigungen.