Ressourcenorientiertes Design

Diese Designanleitung soll Entwicklern dabei helfen, einfache, konsistente und nutzerfreundliche vernetzte APIs zu entwerfen. Gleichzeitig werden die Designs von Socket-basierten RPC APIs mit HTTP-basierten REST APIs zusammengeführt.

Das Design von RPC APIs basiert oft auf Schnittstellen und Methoden. Je mehr davon hinzukommen, desto überwältigender und verwirrender wird die API-Oberfläche für Entwickler, da diese jede einzelne Methode lernen müssen. Es liegt auf der Hand, dass dies zeitaufwendig und fehleranfällig ist.

Als der Architekturstil von REST eingeführt wurde, stand das reibungslose Zusammenspiel mit HTTP/1.1 im Vordergrund, aber auch die Lösung des eben erwähnten Problems im Raum. Das Grundprinzip von REST besteht darin, benannte Ressourcen zu definieren, die sich mit einer kleinen Anzahl von Methoden ändern lassen. Die Ressourcen und Methoden sind auch als Substantive und Verben von APIs bekannt. Beim HTTP-Protokoll sind Ressourcennamen URLs zugeordnet und Methoden sind den HTTP-Methoden POST, GET, PUT, PATCH und DELETE zugeordnet. So müssen Entwickler viel weniger lernen und können sich auf die Ressourcen und ihre Beziehung konzentrieren, unter der Annahme, dass diese dieselbe kleine Anzahl von Standardmethoden haben.

Im Internet sind HTTP REST APIs weit verbreitet. Bereits 2010 waren etwa 74 % der öffentlichen Netzwerk-APIs HTTP REST (oder REST-ähnliche) APIs, von denen die meisten JSON als Übertragungsformat verwendeten.

HTTP/JSON APIs sind im Internet zwar sehr beliebt, doch ist ihr Datendurchsatz geringer als bei herkömmlichen RPC APIs. In den USA besteht beispielsweise zu Spitzenzeiten etwa die Hälfte des Internettraffics aus Videoinhalten. Kaum jemand würde aus naheliegenden Leistungsgründen auf die Idee kommen, HTTP/JSON APIs für solche Inhalte zu verwenden. In Rechenzentren nutzen viele Unternehmen Socket-basierte RPC APIs für den Großteil ihres Netzwerktraffics. Damit lassen sich andere Größenordnungen von (in Byte gemessenen) Daten bewältigen als mit öffentlichen HTTP/JSON APIs.

Tatsächlich haben sowohl RPC APIs als auch HTTP/JSON APIs ihre Berechtigung. Im Idealfall sollte eine API-Plattform alle Arten von APIs bestmöglich unterstützen. Diese Designanleitung unterstützt Sie beim Entwerfen und Erstellen von APIs, die diesem Grundsatz entsprechen. Dazu werden ressourcenorientierte Designprinzipien auf das allgemeine API-Design angewendet und viele gängige Designmuster definiert, um die Benutzerfreundlichkeit zu verbessern und die Komplexität zu verringern.

Hinweis:In dieser Designanleitung wird erläutert, wie Sie REST-Konzepte unabhängig von Programmiersprache, Betriebssystem oder Netzwerkprotokoll auf API-Designs anwenden. Sie erfahren darin NICHT nur, wie Sie REST APIs erstellen.

Was ist eine REST API?

Eine REST API wird in Form von Sammlungen aus individuell adressierbaren Ressourcen – den Substantiven der API – modelliert. Ressourcen werden anhand ihrer Ressourcennamen referenziert und mit nur wenigen Methoden (auch als Verben oder Vorgänge bezeichnet) bearbeitet.

Standardmethoden für Google REST APIs (auch bekannt als REST-Methoden ) sind List, Get, Create, Update und Delete. API-Designern stehen außerdem benutzerdefinierte Methoden – auch benutzerdefinierte Verben bzw. benutzerdefinierte Vorgänge genannt – zur Verfügung. Sie bieten Funktionen, die sich nur schwer den Standardmethoden zuordnen lassen, wie etwa Datenbanktranskationen.

Hinweis: Die Verwendung benutzerdefinierter Verben bedeutet nicht, dass Sie benutzerdefinierte HTTP-Verben erstellen, um benutzerdefinierte Methoden zu unterstützen. Benutzerdefinierte Verben werden bei HTTP-basierten APIs einfach den passendsten HTTP-Verben zugeordnet.

Designablauf

In dieser Designanleitung werden zum Entwerfen ressourcenorientierter APIs die folgenden Schritte empfohlen. Mehr dazu erfahren Sie in den nachfolgenden Abschnitten.

• Ermitteln Sie, welche Ressourcentypen in einer API zur Verfügung gestellt werden.
• Ermitteln Sie die Beziehungen zwischen den Ressourcen.
• Legen Sie die Namensschemas für Ressourcen anhand der Typen und Beziehungen fest.
• Legen Sie die Ressourcenschemas fest.
• Hängen Sie den Ressourcen einen kleinen Satz von Methoden an.

Ressourcen

Ressourcenorientierte APIs werden generell in Form einer Ressourcenhierarchie modelliert. Dabei stellt jeder Knoten eine einfache Ressource oder eine Sammlungsressource dar. Der Einfachheit halber werden sie oft als Ressource bzw. Sammlung bezeichnet.

• Eine Sammlung enthält eine Liste von Ressourcen desselben Typs. Ein Nutzer hat beispielsweise eine Sammlung von Kontakten.
• Eine Ressource besitzt einen Zustand und null oder mehrere Unterressourcen. Jede Unterressource kann eine einfache Ressource oder eine Sammlungsressource sein.

Die Gmail API verfügt beispielsweise über eine Sammlung von Nutzern, von denen jeder eine Sammlung von Nachrichten, Threads und Labels sowie eine Profilressource und mehrere Einstellungsressourcen besitzt.

Obgleich eine gewisse konzeptionelle Ausrichtung zwischen Speichersystemen und REST APIs besteht, muss ein Dienst mit einer ressourcenorientierten API nicht zwingend eine Datenbank sein. Sie können Ressourcen und Methoden damit außerdem auf äußerst flexible Weise interpretieren. Durch das Erstellen eines Kalenderereignisses (Ressource) können beispielsweise zusätzliche Ereignisse für Teilnehmer erstellt, E-Mail-Einladungen an diese gesendet, Konferenzräume reserviert und Zeitpläne für Videokonferenzen aktualisiert werden.

Methoden

Das wichtigste Merkmal einer ressourcenorientierten API ist, dass darin Ressourcen (Datenmodelle) gegenüber den auf den Ressourcen ausgeführten Methoden (Funktionen) Vorrang haben. Eine typische ressourcenorientierte API stellt eine große Anzahl von Ressourcen mit nur wenigen Methoden bereit. Dabei können sowohl Standard- als auch benutzerdefinierte Methoden verwendet werden. In diesem Handbuch sind die Standardmethoden: List, Get, Create, Update und Delete.

Wenn sich API-Funktionen auf einfache Weise einer der Standardmethoden zuordnen lassen, sollte diese Methode im API-Design verwendet werden. Wenn sich die Zuordnung von Funktionen zu Standardmethoden komplexer gestaltet, können benutzerdefinierte Methoden verwendet werden. Benutzerdefinierte Methoden bieten die gleiche Designfreiheit wie herkömmliche RPC APIs. Sie können damit gängige Programmiermuster etwa für Datenbanktransaktionen oder Datenanalysen implementieren.

Beispiele

In den folgenden Abschnitten wird anhand von ein paar Praxisbeispielen gezeigt, wie Sie ein ressourcenorientiertes API-Design auf umfangreiche Dienste anwenden. Weitere Beispiele finden Sie im Repository der Google APIs.

In diesen Beispielen markiert das Sternchen eine bestimmte Ressource in der Liste.

Gmail API

Der Gmail API-Dienst dient zur Implementierung der Gmail API und stellt den Großteil der Gmail-Funktionen bereit. Er verwendet das folgende Ressourcenmodell:

• API-Dienst: gmail.googleapis.com
  • Eine Sammlung von Nutzern: users/*. Jeder Nutzer hat folgende Ressourcen:
    • Eine Sammlung von Nachrichten: users/*/messages/*.
    • Eine Sammlung von Threads: users/*/threads/*.
    • Eine Sammlung von Labels: users/*/labels/*.
    • Eine Sammlung von Änderungsverläufen: users/*/history/*.
    • Eine Ressource, die das Nutzerprofil darstellt: users/*/profile.
    • Eine Ressource, die Nutzereinstellungen darstellt: users/*/settings.

Cloud Pub/Sub API

Der Dienst pubsub.googleapis.com implementiert die Cloud Pub/Sub API, die das folgende Ressourcenmodell definiert:

• API-Dienst: pubsub.googleapis.com
  • Eine Sammlung von Themen: projects/*/topics/*
  • Eine Sammlung von Abonnements: projects/*/subscriptions/*

Hinweis: Bei anderen Implementierungen der Pub/Sub API werden möglicherweise andere Schemas für Ressourcennamen ausgewählt.

Cloud Spanner API

Der Dienst spanner.googleapis.com implementiert die Cloud Spanner API, die das folgende Ressourcenmodell definiert:

• API-Dienst: spanner.googleapis.com
  • Eine Sammlung von Instanzen: . projects/*/instances/*. Jede Instanz hat die folgenden Ressourcen.
  • Eine Sammlung von Vorgängen: projects/*/instances/*/operations/*.
  • Eine Sammlung von Datenbanken: projects/*/instances/*/databases/*. Jede Datenbank hat die folgenden Ressourcen.
    • Eine Sammlung von Vorgängen: projects/*/instances/*/databases/*/operations/*.
    • Eine Sammlung von Sitzungen: projects/*/instances/*/databases/*/sessions/*.