Zum Hauptinhalt springen

Workshop: Goods Century

Goods Century ist ein junger Online Marketplace und benötigt für die Entwicklung ihrer Platform. Das ER-Diagram für die Datenbank wurde bereits designed.

👉 Hier auf db-diagram

User-Stories für das API-Design​

  1. Benutzerregistrierung und Authentifizierung

    • Als neuer Benutzer möchte ich mich registrieren und einloggen, damit ich auf meine Bestellungen und Wunschlisten zugreifen kann.

  2. Produkte durchsuchen und filtern

    • Als Benutzer möchte ich die Produkte durchsuchen, nach Kategorien filtern und nach Preis sortieren können, um das passende Produkt zu finden.

  3. Produktdetails und Bewertungen

    • Als Benutzer möchte ich die Details eines Produkts sowie die Bewertungen anderer Kunden einsehen, um eine Kaufentscheidung treffen zu können.

  4. Warenkorb verwalten

    • Als Benutzer möchte ich Produkte zu meinem Warenkorb hinzufügen und die Menge anpassen können, bevor ich eine Bestellung abschließe.

  5. Bestellungen aufgeben und verwalten

    • Als Benutzer möchte ich eine Bestellung aufgeben und den Status meiner Bestellung verfolgen können, um sicherzustellen, dass sie korrekt verarbeitet wird.

  6. Lieferadresse hinzufügen und verwalten

    • Als Benutzer möchte ich mehrere Lieferadressen speichern und bei einer Bestellung auswählen können, damit die Lieferung reibungslos funktioniert.

  7. Bewertungen abgeben

    • Als Benutzer möchte ich eine Bewertung für ein gekauftes Produkt abgeben, um meine Meinung mit anderen Nutzern zu teilen.

  8. Wunschliste erstellen und verwalten

    • Als Benutzer möchte ich Produkte zu einer Wunschliste hinzufügen und später darauf zugreifen können, um eventuell später zu kaufen.

  9. Zahlungen durchführen

    • Als Benutzer möchte ich bei einer Bestellung eine Zahlungsmethode auswählen und die Zahlung abschließen können.

Workshop-Aufgaben: API-Design mit dem Swagger Editor und Import in Postman​

Für diesen Workshop verwenden wir den Swagger Editor unter https://editor-next.swagger.io/. Hier können wir unsere API-Definition im OpenAPI-Format entwerfen und später in Postman importieren, um die Endpunkte zu testen.

Aufgaben für den API-Design-Workshop​

  1. API-Endpunkte entwerfen

    • Basierend auf den User-Stories, die wir besprochen haben, sollst du die erforderlichen Endpunkte und deren HTTP-Methoden (GET, POST, PUT, DELETE) in Swagger definieren.
    • Beispiele:
      • POST /users/register für die Registrierung eines Benutzers.
      • GET /products?category=electronics&sort=price_asc für das Filtern und Sortieren von Produkten.
    • Überlege dir auch sinnvolle Pfade für verschachtelte Ressourcen, wie z. B. /users/{userId}/orders, um die Bestellungen eines bestimmten Benutzers abzurufen.

  2. Ressourcen-URLs strukturieren

    • Überlege, wie du die URL-Struktur und Hierarchie für die verschiedenen Ressourcen aufbaust. Die Struktur sollte RESTful und logisch sein, sodass die Endpunkte intuitiv und leicht zu verstehen sind.
    • Lege im Swagger Editor für jede Ressource ein passendes Tag fest, z.B. Products, Orders, Users, um die Dokumentation übersichtlicher zu machen.

  3. Datenstrukturen und Beispiel-Responses definieren

    • Definiere für jeden Endpunkt die Request-Bodies und Responses als Schemas.
    • Beispiel: Für den Endpunkt GET /products/{productId} solltest du eine Antwortstruktur erstellen, die die Details des Produkts sowie eine Liste der Bewertungen enthält.
    • Benutze die Example-Funktion im Swagger Editor, um Beispieldaten anzugeben. Das hilft später beim Import in Postman, da du dann bereits realistische Mock-Daten hast.

  4. Statuscodes und Fehler definieren

    • Bestimme die Statuscodes, die für jeden Endpunkt zurückgegeben werden. Definiere auch Fehlerantworten, um eine einheitliche und klare Fehlerbehandlung sicherzustellen.
    • Beispiele:
      • 200 OK für erfolgreiche Abfragen.
      • 201 Created für das Erstellen neuer Ressourcen.
      • 400 Bad Request für fehlerhafte Eingaben.
      • 404 Not Found für nicht existierende Ressourcen.
    • Erstelle bei Bedarf spezielle Fehlerantworten und beschreibe die möglichen Fehler in den Responses-Feldern.

Import der API-Definition in Postman​

  1. Export aus Swagger Editor: Wenn du alle Endpunkte definiert hast, exportiere deine API-Definition als JSON oder YAML. Gehe dazu im Swagger Editor zu File > Download und speichere die Datei lokal.

  2. Import in Postman:

    • Öffne Postman und wähle Import.
    • Lade deine exportierte Swagger-Datei hoch. Postman wird automatisch die API-Endpunkte importieren, die du erstellt hast, und eine Collection daraus erstellen.
    • Nun kannst du die Endpunkte direkt in Postman testen und die Anfragen anpassen, um realistische Tests mit verschiedenen Parametern und Daten vorzunehmen.

Teste deine API in Postman​

  1. API-Definition in Postman importieren

    • Wenn du die API im Swagger Editor entworfen und als OpenAPI-Datei (JSON oder YAML) exportiert hast, importiere sie in Postman.
    • Gehe dazu in Postman auf Import, lade die Datei hoch, und Postman erstellt automatisch eine Collection für die API.

  2. Mock-Server in Postman erstellen

    • Gehe zur Collection der importierten API in Postman.
    • Klicke auf die drei Punkte neben dem Collection-Namen und wähle Mock Collection.
    • Gib dem Mock-Server einen Namen und wähle eine Umgebung (optional) oder erstelle eine neue.
    • Aktiviere Save the mock server URL as an environment variable, sodass du den Mock-Server später einfach in deinen Requests verwenden kannst.
    • Klicke auf Create Mock Server. Postman erstellt eine URL, die als Basis-URL für alle API-Endpunkte dient.

  3. Mock-Responses hinzufügen

    • Für jeden Endpunkt kannst du nun definieren, welche Antwort zurückgegeben wird. Gehe dazu in Postman zu einem bestimmten Request in deiner Collection.
    • Klicke auf den Examples-Tab (unterhalb des Request-Editors) und wähle Add Example.
    • Erstelle hier eine Beispiel-Response für den Endpunkt. Du kannst die erwarteten Statuscodes, Header und einen JSON-Body einfügen.
    • Speichere das Beispiel. Postman verwendet diese Response, wenn du diesen Endpunkt über den Mock-Server aufrufst.

  4. Testen der Mock-API

    • Nun kannst du deine API wie gewohnt testen, aber statt einer echten Backend-Response gibt der Mock-Server die vorbereiteten Antworten zurück.
    • Rufe einen Endpunkt auf, indem du die Mock-Server-URL als Basis-URL verwendest, z.B. https://mock-server-url.com/users.
    • Postman gibt dir die Beispiel-Response zurück, die du für diesen Endpunkt definiert hast.

Vorteile des Mock-Servers​

  • Du kannst die API-Definition und alle Endpunkte testen, ohne ein tatsächliches Backend implementieren zu müssen.
  • Der Mock-Server hilft dir, mögliche Fehler im Design frühzeitig zu identifizieren.
  • Teammitglieder können die API nutzen, ohne dass sie vollständig implementiert ist.

Diese Methode erlaubt dir, das API-Design vollständig zu simulieren und in Postman zu testen. Sobald das Backend entwickelt ist, kannst du die Basis-URL einfach auf die tatsächliche Server-URL ändern und die echten Daten verwenden.