API-Gestaltung

Bestehende Anforderungen als Ausgangspunkt für die API-Gestaltung

Wie die meisten Technologien präsentiert sich eine API als Lösung für ein Problem. Für die richtige Gestaltung Ihrer API müssen Sie zunächst das Problem, das Sie durch die API beheben möchten, klar definieren. Beantworten Sie dazu folgende Fragen:

• Wer sind die Nutzer der API?
• Welche Art von Informationen müssen die Nutzer über die API handhaben?
• Welche Aktionen sollen die Nutzer über die API ausführen können?

Ein Beispiel: Ihre Firma ist ein Lebensmittellieferant und Sie möchten eine API für Ihr Partnernetzwerk einrichten, über die diesen eine Datenbank mit den Restaurants zur Verfügung gestellt wird, die Ihren Lieferservice in Anspruch nehmen.

Die Endnutzer der API in diesem Beispiel sind die Partner Ihrer Firma. Die Partner müssen Daten zu Restaurants bearbeiten und Suchabfragen in den Daten durchführen können. Dabei müssen ihnen spezifische Filter- und Sortierfunktionen zur Verfügung stehen.

Ein anderes Beispiel: Sie sind ein Kalender-SaaS-Anbieter. Sie möchten eine API einrichten, damit andere Frontend-Entwickler weltweit neue mobile und webbasierte Anwendungen auf der Grundlage Ihres Kalendersystems erstellen können.

Die präzise Erfassung der Zielgruppe Ihrer API ist der erste Schritt, um den Nutzern eine gute Entwicklererfahrung bereitstellen zu können. Dadurch stellen Sie Ihre API heraus und verbessern die Nutzungsrate.

Bestandteile einer API

Bei der Gestaltung einer API kommen vier Schlüsselkonzepte zum Einsatz:

• Ressourcen - Elemente, mit denen die Nutzer über Ihre API interagieren. Ressourcen werden anhand eines Pfads eindeutig identifiziert. In Kombination mit dem Endpunkt der API steht eine eindeutige Adresse für die Ressourcen im Web zur Verfügung. Ein Beispiel: „Calendars“ ist der Name einer Ressource, die einer Liste von Kalendern entspricht. Der Pfad der Ressource lautet /calendars.
• Operationen - Aktionen, die mit Ihren Ressourcen ausgeführt werden können. Die gängigsten Operationen sind GET (Lesen), POST (Erstellen), PUT (Aktualisieren) und DELETE (Löschen). Ein Beispiel: „List all Calendars“ (Alle Kalender auflisten) ist der Name einer Operation, die auf die GET-Methode für die „Calendars“-Ressource zurückgreift.
• Datentypen - Beschreibungen der realen Daten, die über das Netzwerk ausgetauscht werden. Ein Beispiel: „Calendar“ ist der Name eines Datentyps, der sämtliche Eigenschaften eines Kalenders beschreibt, wie z. B. Name, Eigentümer und Verweis auf die zugehörigen Ereignisse. Die Operation „List all Calendars“ (Alle Kalender auflisten) gibt eine Liste von Kalenderdatentypen zurück.
• Komponenten - Elemente, die in der gesamten API-Definition wiederverwendet werden können. Ein Beispiel: Wenn Sie denselben Abfrageparameter in verschiedenen Operationen verwenden müssen, können Sie ihn als Komponente erstellen und sich nach Bedarf in beliebig vielen Operationen auf ihn beziehen.

Darüber hinaus tragen noch andere nützliche Elemente zur Gestaltung einer API bei:

• Endpunkte - Haupteingangspunkte für APIs im Web. Ein Endpunkt besteht aus einem Schema, wie z. B. HTTPS, und einem Host, wie z. B. www. calendar-api.com.
• Text-Blöcke - Dienen der Eingabe von freiem Text (einschließlich Markdown) und können an einer beliebigen Stelle in Ihrem API-Design platziert werden. Verwenden Sie Textblöcke, um transversale Themen wie Authentifizierung und Fehlerverwaltung zu erläutern.
• Sections - Dienen einer aussagekräftigen Gruppierung von Ressourcen und Datentypen. Verwenden Sie Sections, um Ihre API klarer zu strukturieren und benutzerfreundlicher zu gestalten. Sie können Elemente in die Sections im linken Fensterbereich ziehen und dort ablegen und darüber hinaus die Sections untereinander neu anordnen.

In Talend Cloud API Designer können Sie diese Elemente über das +-Menü im linken Fensterbereich erstellen.

Endpunkte werden im allgemeinen Informationsfenster erstellt. Um auf dieses Fenster zuzugreifen, klicken Sie auf den Namen Ihrer API am oberen Rand des linken Fensterbereichs. Endpunkte können veröffentlicht (Published) bzw. nicht veröffentlicht (Not published) werden. Ein veröffentlichter Endpunkt wird in der Live-Dokumentation sowie im API-Portal angezeigt.