API-Design
Von den Anforderungen zur API
Wie die meisten Technologien stellt eine API eine Lösung für ein Problem dar. Um die richtige API zu entwerfen, müssen Sie sicherstellen, dass das zugrunde liegende Problem klar definiert ist, indem Sie die folgenden Fragen beantworten:
- Für welche Zielgruppe wird diese API konzipiert?
- Welche Art von Informationen werden die Nutzer über die API verarbeiten?
- Welche Aktionen werden die Nutzer über die API durchführen?
Als Essenslieferdienst möchten Sie für Ihr Partnernetzwerk beispielsweise eine API zum Durchsuchen einer Datenbank mit Restaurants erstellen, für die Sie einen Lieferservice anbieten.
In diesem Beispiel richtet sich Ihre API an Partner Ihres Unternehmens. Sie müssen Daten zu Restaurants verarbeiten und Suchanfragen für die Daten durchführen, einschließlich bestimmter Filter- und Sortierfunktionen.
Ein weiteres Beispiel: Als Anbieter einer Online-Kalenderlösung möchten Sie unter Umständen eine API erstellen, damit andere Front-End-Entwickler weltweit neue mobile und Webanwendungen auf Basis Ihres Kalendersystems erstellen können.
Über die Bedürfnisse der Nutzer Ihrer API nachzudenken, ist der erste Schritt, um ihnen ein gutes Entwicklererlebnis zu bieten. Dies wird dazu beitragen, dass sich Ihre API abhebt und deren Nutzung steigt.
Die Elemente, aus denen eine API besteht
Beim Entwurf einer API werden vier Schlüsselkonzepte verwendet:
- Eine Ressource ist ein Element, mit dem Ihre Nutzer über Ihre API interagieren. Ressourcen werden eindeutig durch einen Pfad angegeben, der zusammen mit dem API-Endpunkt eine eindeutige Adresse für eine Ressource im Web bildet. „Kalender“ ist beispielsweise der Name einer Ressource, die einer Liste von Kalendern entspricht und deren Pfad auf /calendars lautet.
- Eine Operation ist die Aktion, die auf Ihre Ressourcen angewendet werden kann. Die gängigsten Operationen sind GET (Lesen), POST (Erstellen), PUT (Aktualisieren) und DELETE (Löschen). „Alle Kalender auflisten“ ist beispielsweise der Name eines Vorgangs, der die GET-Methode für die Ressource „Kalender“ verwendet.
- Ein Datentyp ist eine Beschreibung der tatsächlichen Daten, die über das Netzwerk ausgetauscht werden. „Kalender“ ist beispielsweise der Name eines Datentyps, der alle Eigenschaften eines Kalenders beschreibt, wie seinen Namen, den Besitzer und einen Verweis auf die zugehörigen Ereignisse. Der Vorgang „Alle Kalender auflisten“ gibt eine Liste von „Kalender“-Datentypen zurück.
- Eine Komponente ist ein Element, das in der gesamten API-Definition wiederverwendet werden kann. Wenn Sie beispielsweise denselben Abfrageparameter in mehreren Operationen verwenden müssen, können Sie ihn als Komponente erstellen und in beliebig vielen Operationen darauf verweisen.
Es gibt weitere nützliche Elemente, aus denen eine API besteht:
- Ein Endpunkt ist der zentrale Einstiegspunkt für Ihre API im Web. Ein Endpunkt besteht aus einem Schema wie HTTPS und einem Host wie „www.calendar-api.com“.
- Mit einem Textblock können Sie beliebigen Text (einschließlich Markdown) frei eingeben, der an beliebiger Stelle in Ihrem API-Design platziert werden kann. Verwenden Sie Textblöcke, um übergreifende Themen wie Authentifizierung und Fehlerbehandlung zu erläutern.
- Ein Abschnitt wird verwendet, um Ressourcen und Datentypen sinnvoll zu gruppieren. Verwenden Sie diese, um Ihr API-Design übersichtlicher und entwicklerfreundlicher zu gestalten. Sie können Elemente per Drag & Drop in Abschnitte im linken Bereich verschieben und die Abschnitte auch untereinander neu anordnen.
Im API Designer können Sie diese Elemente über das Menü Create new (Neu erstellen) in der oberen rechten Ecke erstellen.
Server-URLs werden im Bildschirm für allgemeine Informationen erstellt. Eine Server-URL kann den Status Published (Veröffentlicht) oder Not published (Nicht veröffentlicht) aufweisen. Wenn sie veröffentlicht ist, wird sie in der Live-Dokumentation angezeigt.
