---
type: Runbook
status: ACTIVE
owner: QA Specialist
tags: [postman, testing, api, backend]
last_update: 2026-04-03
---
# Runbook: API-Tests mit Postman (für Nicht‑Programmierer)

> Ziel: Alle Kern-APIs der Meldestelle lokal prüfen – sicher, reproduzierbar und ohne Programmierkenntnisse.

Inhalt:
1. Voraussetzungen (Docker-Profile starten)
2. Postman einrichten (Collection + Environment)
3. Login/Token beschaffen
4. Smoke‑Tests (System & Health)
5. Ping‑Service durchtesten (ohne/mit Login, Resilience)
6. Master‑Data & Pferde (Beispiele)
7. Empfohlene Test‑Reihenfolge
8. Troubleshooting & FAQ

---

## 1. Voraussetzungen

Bitte sicherstellen, dass die lokale Umgebung läuft:

- Infrastruktur starten: `docker compose --profile infra up -d`
- Backend starten: `docker compose --profile backend up -d`

Standard‑Ports (lokal):
- Gateway: `http://localhost:8081`
- Keycloak: `http://localhost:8180`
- Ping‑Service (direkt): `http://localhost:8082`
- ZNS‑Import (direkt): `http://localhost:8095`
- Consul: `http://localhost:8500`

Hinweis: Warte 30–60 Sekunden nach dem Start, bis alle Dienste „UP“ sind.

---

## 2. Postman einrichten

### 2.1 Collection importieren
1. Postman öffnen → „Import“ → Datei wählen:
```
backend/infrastructure/gateway/src/main/resources/static/docs/postman/Meldestelle_API_Collection.json
```
2. Die Collection „Meldestelle API Collection“ erscheint links.

### 2.2 Environment anlegen (z. B. „Meldestelle Local“)
Trage folgende Variablen ein:

| Variable | Wert (Initial) | Beschreibung |
|---|---|---|
| `gateway_url` | `http://localhost:8081` | API‑Gateway Einstieg |
| `auth_url` | `http://localhost:8180/realms/meldestelle/protocol/openid-connect/token` | Token‑Endpoint |
| `client_id` | `postman-client` | Keycloak Client |
| `client_secret` | `postman-secret-123` | Secret zum Client |
| `username` | `admin` | Testuser |
| `password` | `Admin#1234` | Passwort |
| `ping_url` | `http://localhost:8082` | Direkter Ping‑Service |
| `zns_url` | `http://localhost:8095` | Direkter ZNS‑Import |
| `consul_url` | `http://localhost:8500` | Consul UI |
| `auth_token` | (leer) | Wird nach Login automatisch befüllt |
| `horse_id` | (leer) | Wird bei Pferde‑Tests befüllt |
| `country_id` | (leer) | Wird bei Länder‑Tests befüllt |

---

## 3. Login/Token beschaffen

In Postman im Reiter „Authorization“ (Request „Login“ in der Collection nutzen oder manuell):
- Type: „OAuth 2.0“
- Grant Type: „Password Credentials“
- Access Token URL: `{{auth_url}}`
- Client ID: `{{client_id}}`
- Client Secret: `{{client_secret}}`
- Username: `{{username}}`
- Password: `{{password}}`
- Button „Get New Access Token“ → „Use Token“

Das Token wird im Environment als `auth_token` gespeichert (Pre‑Request Scripts der Collection setzen es automatisch, sofern vorhanden).

---

## 4. Smoke‑Tests (immer zuerst)

Zweck: Schnell prüfen, ob das System erreichbar und „UP“ ist.

1) API‑Gateway Info
- Methode: `GET`
- URL: `{{gateway_url}}/actuator/info`
- Auth: Keine
- Erwartet: `200 OK` (leerer JSON‑Body ist aktuell normal)

2) API‑Gateway Health
- Methode: `GET`
- URL: `{{gateway_url}}/actuator/health`
- Auth: Keine
- Erwartet: `200 OK` mit `{ "status": "UP" }`

3) OpenAPI (optional)
- Methode: `GET`
- URL: `{{gateway_url}}/v3/api-docs`
- Erwartet: `200 OK` (OpenAPI JSON)

---

## 5. Ping‑Service Tests

### 5.1 Öffentlich (ohne Login)
1) Simple Ping
- `GET {{gateway_url}}/api/ping/simple`
- Erwartet: `200 OK` mit `{"status":"pong", ...}`

2) Health
- `GET {{gateway_url}}/api/ping/health`
- Erwartet: `200 OK` mit `{"status":"up", ...}`

3) Public Ping
- `GET {{gateway_url}}/api/ping/public`
- Erwartet: `200 OK`

### 5.2 Sicherheit (Negativ‑Test, ohne Login)
1) Secure Ping (unauthenticated)
- `GET {{gateway_url}}/api/ping/secure`
- Erwartet: `401 Unauthorized`

2) Sync Ping (unauthenticated)
- `GET {{gateway_url}}/api/ping/sync`
- Erwartet: `401 Unauthorized`

### 5.3 Authentifiziert (mit Token)
1) Secure Ping (authenticated)
- `GET {{gateway_url}}/api/ping/secure`
- Auth: OAuth 2.0 (Token)
- Erwartet: `200 OK` mit `{"status":"secure-pong", ...}`

2) Sync Ping (authenticated)
- `GET {{gateway_url}}/api/ping/sync?lastSyncTimestamp=0`
- Erwartet: `200 OK` (Liste von Events)

### 5.4 Resilience (Circuit Breaker Demo)
1) Enhanced Ping (normal)
- `GET {{gateway_url}}/api/ping/enhanced` → `200 OK`

2) Enhanced Ping (Fehler provozieren)
- `GET {{gateway_url}}/api/ping/enhanced?simulate=true` mehrfach senden
- Erwartet: teils `500`, danach Fallback‑Antwort mit `circuitBreakerState: "OPEN"`

---

## 6. Master‑Data & Pferde (Beispiele)

Hinweis: Endpunkte können sich ändern. Maßgeblich ist die OpenAPI unter `{{gateway_url}}/v3/api-docs` sowie die importierte Postman‑Collection.

### 6.1 Countries
- Create: `POST {{gateway_url}}/api/masterdata/countries` (Body siehe Collection)
- Read: `GET {{gateway_url}}/api/masterdata/countries/{{country_id}}`
- Erwartet: `201 Created` bei Anlage, `200 OK` beim Lesen.

### 6.2 Horse Registry
- Create: `POST {{gateway_url}}/api/horses` → speichert `{{horse_id}}`
- Get: `GET {{gateway_url}}/api/horses/{{horse_id}}`
- Delete (optional): `DELETE {{gateway_url}}/api/horses/{{horse_id}}`

---

## 7. Empfohlene Test‑Reihenfolge (Checkliste)

1) Infrastruktur & Backend starten (Docker Profiles)
2) Collection importieren, Environment setzen
3) Smoke‑Tests (Info, Health, OpenAPI)
4) Ping öffentlich (simple, health, public)
5) Negativ‑Tests (secure/sync ohne Token → 401)
6) Login/Token holen
7) Ping authentifiziert (secure/sync)
8) Resilience testen (enhanced, simulate=true)
9) Optionale Domänen‑Tests (Countries, Horses)

---

## 8. Troubleshooting & FAQ

- 401 Unauthorized trotz Login:
  - Token wirklich gesetzt? In Postman „Use Token“ klicken; im Request unter „Authorization“ prüfen.
  - Uhrzeit/Zeitzone korrekt? Abgelaufene Tokens werden abgewiesen.
- 502/503 vom Gateway:
  - Service wirklich „UP“? `{{gateway_url}}/actuator/health` und Container‑Logs prüfen: `docker compose ps` / `docker compose logs -f <service>`
- Keycloak nicht erreichbar:
  - Warten Sie nach Start 30–60 Sekunden. Prüfen: `http://localhost:8180`.
- OpenAPI leer oder 404:
  - Backend neu gestartet? Warten, bis Gateway die Routen geladen hat.

Weitere Details und Hintergründe finden Sie in der ursprünglichen, technischen Langfassung der QA‑Dokumentation (siehe Archiv‑Hinweis unten).

---

Quellen & Verweise:
- Postman‑Collection: `backend/infrastructure/gateway/src/main/resources/static/docs/postman/Meldestelle_API_Collection.json`
- Backend‑Referenz: `docs/05_Backend/Services/PingService_Reference.md`
- OpenAPI: `{{gateway_url}}/v3/api-docs`

Archiv‑Hinweis:
- Die frühere, sehr detaillierte Arbeitsversion „Postman Tests — Vollständige Dokumentation“ aus dem Agents‑Besprechungsordner wurde in dieses Runbook konsolidiert und ins Archiv verschoben.