8. Der RdvMedecins-Server, eine Blackbox
Die Beispiele 22 bis 25 sowie die Fallstudie kommunizieren mit einem Server: dem JSON-Server der Anwendung [RdvMedecins]. Es ist der [NestJS]-Server der Kurse [React], [Vue.js] und [Angular]: der Server des Kurses [NestJS], dessen Controller keine HTML-Seiten mehr erzeugen, sondern JSON-Antworten liefern. Wer diese Kurse bereits kennt, kennt dieses Kapitel schon; es wird hier nahezu unverändert wiedergegeben. Es genügt, sich auf den Abschnitt zur Authentifizierung zu konzentrieren, der erklärt, was sich für eine mobile Anwendung ändert.
In diesem Kurs ist dieser Server eine Blackbox: Sie müssen nicht wissen, wie er geschrieben ist. Wichtig ist allein seine API, also die Liste der HTTP-Anfragen, die er akzeptiert, und der Antworten, die er zurückliefert. Das ist die typische Situation eines Client-Entwicklers: Die API ist ein Vertrag, und das Server-Team kann hinter diesem Vertrag alles ändern, was es möchte. Der Quellcode wird mitgeliefert (Ordner [rdvmedecins-nestjs-json]) und ist für neugierige Leser ausführlich kommentiert.
Dieses Kapitel erklärt, wie der Server installiert wird, beschreibt seine API und fragt ihn mit [curl] ab.
8.1. Die Anwendung RdvMedecins
Die Anwendung verwaltet die Termine einer Arztpraxis. Sie kennt drei Rollen:
Rolle | Wer | Was sie tun können |
[ADMIN] | Der Administrator ([admin]) | Termine für alle Patienten vereinbaren und stornieren; Ärzte und Klienten verwalten |
[DOCTOR] | Ärzte ([pelissier], [tatou], [dupont]) | Termine für alle Patienten vereinbaren und stornieren; in den Terminkalendern alle Namen einsehen |
[USER] | Patienten ([martin], [durand], [bistrou], [german]) | Für sich selbst Termine buchen; ihre Termine stornieren; ihr Konto verwalten. In einem Terminkalender sehen sie die Namen anderer Patienten nicht |
Die Demokonten verwenden ihren Login als Passwort. Die Verwaltungsregeln werden vom Server unabhängig vom Client geprüft:
- keine Termine in der Vergangenheit;
- nur ein bevorstehender Termin pro Patient;
- ein Zeitfenster kann pro Tag nur einmal gebucht werden;
- zwei Ärzte (oder zwei Klienten) dürfen nicht denselben Vor- und Nachnamen haben; ein Login gehört zu nur einem Konto;
- ein Arzt mit Terminen kann nicht gelöscht werden;
- Ein Datensatz, der in der Zwischenzeit von jemand anderem geändert wurde, kann nicht überschrieben werden (optimistisches Sperren);
- einem Patienten wird nie der Name eines anderen Patienten zugewiesen.
8.2. Installation
Sie benötigen [Node.js] und einen [MySQL] (oder [MariaDB])-Server: Deren Installation wird im Anhang beschrieben.
- Die Datenbank. Das Skript [database/dbrdvmedecins2.sql] erstellt die Datenbank [dbrdvmedecins2], ihre Tabellen und ihre Beispieldaten. Mit [Laragon] führen Sie es in [HeidiSQL] aus (Menü Datei / SQL-Datei ausführen); in der Befehlszeile:
| mysql -u root -p < database/dbrdvmedecins2.sql
|
Das Skript beginnt immer mit einer leeren Datenbank: Sie können es erneut ausführen, um die Anfangsdaten wiederherzustellen.
- Bibliotheken. In einem Konsolenfenster, das im Ordner [rdvmedecins-nestjs-json] geöffnet ist:
- Konfiguration. Kopieren Sie die Datei [.env.example] nach [.env] (unter [Windows]: [copy .env.example .env]) und ändern Sie sie anschließend:
| # -----------------------------------------------------------------------
# Beispielhafte Konfigurationsdatei.
# Kopieren Sie diese Datei nach [.env] und passen Sie dann die Werte an Ihren Rechner an.
# Die Datei [.env] darf niemals weitergegeben oder committet werden (Passwörter).
# -----------------------------------------------------------------------
# Listening-Port des JSON-Servers
PORT=8080
# Verbindungsparameter für die MySQL-Datenbank [dbrdvmedecins2]
# (Skript: database/dbrdvmedecins2.sql)
DB_HOST=localhost
DB_PORT=3306
DB_USERNAME=root
DB_PASSWORD=
DB_DATABASE=dbrdvmedecins2
# true: zeigt in der Konsole die an MySQL gesendeten SQL-Abfragen an
DB_LOGGING=false
# -----------------------------------------------------------------------
# Authentifizierung
# -----------------------------------------------------------------------
# geheimer Schlüssel zum Signieren/Prüfen von JWT-Tokens - MUSS geändert werden
# in der Produktion (eine lange Zufallszeichenfolge, niemals committet).
JWT_SECRET=change-me-to-a-long-random-string
# Gültigkeitsdauer eines JWT-Tokens in Sekunden (7200 s = 2 h). Das Cookie,
# das das Token trägt, hat dieselbe Lebensdauer.
JWT_EXPIRES_IN_SECONDS=7200
# in der Produktion auf true setzen (Website über HTTPS ausgeliefert): Das
# Authentifizierungs-Cookie wird dann nie über eine unverschlüsselte Verbindung gesendet.
COOKIE_SECURE=false
# -----------------------------------------------------------------------
# Schutz vor Bots
# -----------------------------------------------------------------------
# Login: Anzahl der zulässigen Fehlversuche (falsches CAPTCHA oder Passwort) für
# denselben Login von derselben IP-Adresse, bevor dieses Paar gesperrt wird ...
LOGIN_MAX_FAILURES=5
# ... für diese Dauer (eine IP-Adresse wird außerdem gesperrt, wenn sie 5-mal mehr
# Fehlversuche ansammelt, alle Logins zusammengenommen)
LOGIN_BLOCK_MINUTES=15
# Erstellung von Kundenkonten: maximale Anzahl der pro Stunde erstellten Konten
# von derselben IP-Adresse. In einem Klassenraum gehen oft alle Rechner
# über dieselbe Adresse ins Netz: bei Bedarf erhöhen.
REGISTRATION_MAX_PER_HOUR=10
# CAPTCHA-TESTMODUS: Hat diese Variable einen Wert, wird dieser Wert als
# Antwort auf JEDES CAPTCHA akzeptiert. Praktisch, um
# die API mit curl abzufragen (in einer Konsole kann man das Bild nicht "lesen").
# In der Produktion LEER lassen.
CAPTCHA_TEST=
# -----------------------------------------------------------------------
# Produktion
# -----------------------------------------------------------------------
# Ordner des kompilierten Web-Clients, der von diesem Server ausgeliefert wird (Standard: client/)
# CLIENT_DIR=client
# auf true setzen, wenn der Server hinter einem Proxy liegt (nginx ...)
TRUST_PROXY=false
|
- Zeile 8: Der Server lauscht auf Port 8080;
- Zeilen 12–16: die Verbindung zu [MySQL]. Mit [Laragon] hat der Benutzer [root] kein Passwort: Die Standardwerte passen;
- Zeile 25: der geheime Schlüssel, mit dem die Authentifizierungs-Token signiert werden;
- Zeilen 38–45: Anti-Bot-Maßnahmen (Sperre nach mehreren fehlgeschlagenen Anmeldeversuchen, Anzahl der pro Stunde erstellten Konten);
- Zeile 51: CAPTCHA-Testmodus. Die Anmeldeseite verlangt, dass Sie die Zeichen eines Bildes eingeben, was von einer Konsole aus unmöglich ist. Hat diese Variable einen Wert, wird dieser Wert als Antwort auf jedes CAPTCHA akzeptiert, ähnlich den „Testschlüsseln“, die [Google] für sein [reCAPTCHA] bereitstellt. Tragen Sie für die Tests mit [curl] in diesem Kapitel [CAPTCHA_TEST=test] ein. Die automatisierten Tests, die die Screenshots für diesen Kurs erzeugt haben, verwenden ebenfalls diesen Wert. Lassen Sie diese Variable in der Produktion LEER;
- Zeilen 57–59: zwei Einstellungen für die Produktion (siehe Kapitel „Bereitstellung“).
- Starten.
Die Konsole zeigt an (Auszug):
| [Nest] LOG [NestFactory] Starting Nest application...
[Nest] WARN [RdvMedecins] captcha TEST MODE active (CAPTCHA_TEST in .env): never use it in production
[Nest] LOG [RoutesResolver] ScheduleController {/api/schedule}:
[Nest] LOG [RouterExplorer] Mapped {/api/schedule, GET} route
[Nest] LOG [RoutesResolver] AppointmentsController {/api/appointments}:
...
[Nest] LOG [NestApplication] Nest application successfully started
[Nest] LOG [RdvMedecins] JSON server started: http://localhost:8080/api
|
Ist die Datenbank nicht erreichbar ([MySQL]-Server angehalten, falsches Passwort), beendet sich der Server sofort mit einer Verbindungsfehlermeldung.
Alle URLs beginnen mit [/api]. Eine erfolgreiche Anfrage erhält einen Statuscode 2xx und in ihrem Body die angeforderten Daten im JSON-Format. Eine abgelehnte Anfrage erhält einen Code 4xx oder 5xx und im Body ein Objekt, das IMMER dasselbe Format hat:
| {
"statusCode": 400,
"key": "ERRORS.INVALID_FORM",
"params": { "min": "6" },
"fields": { "lastName": "ERRORS.LASTNAME_REQUIRED", "password": "ERRORS.PASSWORD_TOO_SHORT" }
}
|
- [statusCode]: der HTTP-Code, im Body wiederholt;
- [key]: der Übersetzungsschlüssel der Meldung. Der Server liefert nie Text zur Anzeige: Er kennt die Sprache des Benutzers nicht mehr. Der Client übersetzt den Schlüssel anhand seiner Wörterbücher (siehe Beispiel 21);
- [params] (optional): die Parameter der Meldung ([At least {min} characters], [Try again in {minutes} minute(s)]);
- [fields] (optional): bei einem abgelehnten Formular der Fehler zu jedem Feld.
Verwendete Codes:
Code | Bedeutung | Beispiele für Schlüssel |
400 | Ungültige Anfrage | [ERRORS.INVALID_FORM] (+ fields), [ERRORS.INVALID_DATE], [ERRORS.WRONG_CAPTCHA], [ERRORS.CHOOSE_PATIENT], [ERRORS.WRONG_CURRENT_PASSWORD], [ERRORS.BAD_REQUEST]... |
401 | Nicht authentifiziert | [ERRORS.AUTH_REQUIRED] (kein Token), [ERRORS.SESSION_EXPIRED] (ungültiges oder abgelaufenes Token), [LOGIN.ERROR] |
403 | Zugriff verweigert | [ERRORS.FORBIDDEN] (unzureichende Rolle), [ERRORS.CAPTCHA_BEFORE_ACCOUNT] (kein Pass) |
404 | Nicht gefunden | [ERRORS.NOT_FOUND], [ERRORS.DOCTOR_NOT_FOUND], [ERRORS.APPOINTMENT_NOT_FOUND]... |
409 | Verletzung einer Geschäftsregel | [ERRORS.PAST_DATE], [ERRORS.SLOT_ALREADY_BOOKED], [ERRORS.LOGIN_TAKEN], [ERRORS.CONCURRENT_UPDATE]... |
415 | POST, der nicht im JSON-Format vorliegt | [ERRORS.JSON_REQUIRED] |
429 | Zu viele Versuche | [ERRORS.TOO_MANY_ATTEMPTS], [ERRORS.TOO_MANY_ACCOUNTS] (+ params.minutes) |
500 | Serverfehler | [ERRORS.SERVER_ERROR] |
8.4. Authentifizierung
Der Client authentifiziert sich mit [POST /api/auth/login] unter Angabe von Benutzername, Passwort und CAPTCHA-Antwort. Als Gegenleistung sendet der Server im Header [Set-Cookie] seiner Antwort einen Cookie, der ein signiertes JWT-Token enthält:
| Set-Cookie: rdvmedecins_jwt=eyJhbGciOiJIUzI1NiIs...; Max-Age=7200; Path=/api; HttpOnly; SameSite=Strict
|
Der Client muss diesen Cookie nun im [Cookie]-Header bei jeder Anfrage an [/api] mitsenden: So weiß der Server, wer die Anfrage stellt.
Dieser Server wurde für Web-Clients entworfen, und seine Entwurfsentscheidungen sind von den spezifischen Risiken von Webbrowsern geprägt:
- [HttpOnly]: Der Code der Seite ([JavaScript]) KANN diesen Cookie NICHT lesen. Ein in die Seite eingeschleustes bösartiges Skript könnte das Token daher nicht stehlen. Folge für den Client: Er kann nicht selbst feststellen, ob er angemeldet ist. Er fragt den Server ([GET /api/auth/me]);
- [Path=/api]: Der Cookie wird nur in Anfragen an die API mitgesendet;
- [SameSite=Strict]: Der Browser hängt den Cookie nur an Anfragen an, die von einer Seite dieser Website gesendet werden. Eine bösartige Seite auf einer anderen Website kann den Browser nicht dazu bringen, im Namen des Benutzers zu handeln (ein sogenannter CSRF-Angriff);
- [Max-Age=7200]: Er läuft nach zwei Stunden ab, zugleich mit dem Token.
Eine zweite Schutzmaßnahme gegen CSRF-Angriffe: Der Server weist (415) jede POST-Anfrage ab, deren Body nicht im JSON-Format vorliegt. Ein manipuliertes HTML-Formular auf einer anderen Website kann kein JSON senden.
Und wie sieht es bei einer mobilen App aus? Es gibt keinen Browser: Niemand speichert den Cookie oder sendet ihn von allein zurück. Die App übernimmt diese Rolle, indem sie den Header [Set-Cookie] in den Antworten liest und den Header [Cookie] in die Anfragen schreibt (Beispiel 23). Die Attribute [HttpOnly] und [SameSite] gelten nur für Browser: Auf die App haben sie keine Wirkung, ebenso wenig wie auf [curl]. Dieselbe [Flutter]-Anwendung verhält sich, wenn sie für das Web kompiliert wird, allerdings wie Browser: Der Cookie wird vom Browser verwaltet, sofern Anwendung und API denselben Ursprung haben (siehe Beispiel 22 und Kapitel „Bereitstellung“).
8.5. Die API
Methode | Adresse | Rollen | Gesendeter Body / Antwort |
GET | [/api/captcha] | öffentlich | Antwort: [{ id, svg }] |
POST | [/api/auth/login] | öffentlich | [{ login, password, captchaId, captcha }]; Antwort: [{ login, name, role }] + Cookie |
POST | [/api/auth/logout] | öffentlich | [{}] ; löscht den Cookie |
GET | [/api/auth/me] | angemeldet | Antwort: [{ login, name, role }] |
GET | [/api/schedule?doctorId=&day=] | alle | Antwort: der Terminkalender (ohne doctorId: bei einem DOCTOR sein eigener) |
POST | [/api/appointments] | alle | [{ day, slotId, clientId }] (clientId wird bei einem USER ignoriert); 201 |
DELETE | [/api/appointments/:id] | alle | Ein USER storniert nur seine eigenen |
GET | [/api/doctors] | alle | die Liste (mit Login für ADMIN) |
GET | [/api/clients] | ADMIN, DOCTOR | die Liste (mit Login für ADMIN) |
GET | [/api/doctors/:id], [/api/clients/:id] | ADMIN | ein Datensatz |
POST | [/api/doctors], [/api/clients] | ADMIN | [{ title, firstName, lastName, login?, password? }]; 201 |
PUT | [/api/doctors/:id], [/api/clients/:id] | ADMIN | [{ title, firstName, lastName, login?, password?, version }] |
DELETE | [/api/doctors/:id], [/api/clients/:id] | ADMIN | Antwort: [{}] |
POST | [/api/register/access] | öffentlich | [{ captchaId, captcha }]; stellt ein Token aus (Cookie) |
GET | [/api/register/access] | öffentlich | Antwort: [{ valid }] |
POST | [/api/register] | öffentlich + Pass | [{ title, firstName, lastName, login, password, confirmation }]; 201 |
GET | [/api/my-area] | USER | Antwort: [{ patient, appointments }] |
GET | [/api/my-account] | USER | Antwort: [{ title, firstName, lastName, login, version }] |
PUT | [/api/my-account] | USER | [{ title, firstName, lastName, login, password?, confirmation?, currentPassword, version }] |
DELETE | [/api/my-account] | USER | [{ currentPassword }]; löscht das Konto und seine Termine |
Ein Eintrag im Terminkalender ([GET /api/schedule]) beschreibt ein Zeitfenster UND das, was der angemeldete Benutzer damit tun darf:
| { "id": 3, "startHour": 8, "startMinute": 40, "endHour": 9, "endMinute": 0,
"free": false,
"patient": { "title": "Mme", "firstName": "Alice", "lastName": "DURAND" },
"mine": false, "bookable": false, "appointmentId": 2 }
|
- [free]: Ist das Zeitfenster an diesem Tag verfügbar?
- [patient]: der Patient des Termins. Bei einem angemeldeten Patienten ist dies gleich [null], außer bei SEINEM EIGENEN Termin: Die Namen anderer Patienten werden nie gesendet;
- [mine]: Dies ist der Termin des angemeldeten Patienten;
- [bookable]: Kann der Benutzer dieses Zeitfenster buchen (frei, nicht in der Vergangenheit und, bei einem Patienten, kein bevorstehender Termin)?
- [appointmentId]: ausgefüllt, wenn der Benutzer diesen Termin stornieren kann.
Der Server ENTSCHEIDET; der Client zeigt an. Und selbst wenn ein Client schummeln würde (indem er eine Schaltfläche „Buchen“ anzeigt, wo er es nicht sollte), würde der Server bei der Buchung alles noch einmal prüfen.
8.6. Die API mit curl abfragen
Der Ordner [curl] auf dem Server enthält die JSON-Request-Bodys dieses Kapitels, eine Datei pro Anfrage. Zum Beispiel [curl/login-admin.json]:
| { "login": "admin", "password": "admin", "captchaId": "-", "captcha": "test" }
|
Befehle werden in einer Konsole eingegeben, die im Verzeichnis [rdvmedecins-nestjs-json] geöffnet ist. Einige Optionen von [curl]:
- [-i]: zusätzlich die Antwort-Header anzeigen; [-s]: ohne Fortschrittsanzeige;
- [--json @file]: den Inhalt der Datei per POST senden, mit dem Header [Content-Type: application/json] (curl 7.82 und neuer; bei einer älteren Version verwenden Sie [-H "Content-Type: application/json" -d @file]);
- [-X PUT], [-X DELETE]: die HTTP-Methode;
- [-c cookies.txt]: die empfangenen Cookies in dieser Datei speichern; [-b cookies.txt]: sie zurücksenden. So bleibt [curl] von einem Befehl zum nächsten „angemeldet“, genau wie es ein Browser tun würde.
Unter [PowerShell] müssen Sie [curl.exe] eingeben und nicht [curl] (das dort auf einen anderen Befehl verweist). Die teils recht langen JSON-Antworten wurden für dieses Dokument formatiert, und die Header [Date], [ETag], [Connection], und [Keep-Alive] wurden entfernt.
8.6.1. Anmeldung
Zuerst das CAPTCHA (das Bild ist zugeschnitten):
| $ curl -i http://localhost:8080/api/captcha
HTTP/1.1 200 OK
Cache-Control: no-store
Content-Type: application/json; charset=utf-8
Content-Length: 11428
{"id": "968678a8-25f0-4892-9fc4-bd93533dab33", "svg": "<svg xmlns=\"http://www.w3.org/2000/svg\" width=\"150..."}
|
Ohne Token liefert eine geschützte URL eine 401-Antwort:
| $ curl -i http://localhost:8080/api/doctors
HTTP/1.1 401 Unauthorized
Content-Type: application/json; charset=utf-8
Content-Length: 47
{"statusCode": 401, "key": "ERRORS.AUTH_REQUIRED"}
|
Ein falsches CAPTCHA, gefolgt von einem falschen Passwort:
| $ curl -i --json @curl/login-wrong-captcha.json http://localhost:8080/api/auth/login
HTTP/1.1 400 Bad Request
Content-Type: application/json; charset=utf-8
Content-Length: 91
{"statusCode": 400, "key": "ERRORS.WRONG_CAPTCHA", "fields": {"captcha": "ERRORS.WRONG_CAPTCHA"}}
|
| $ curl -i --json @curl/login-wrong-password.json http://localhost:8080/api/auth/login
HTTP/1.1 401 Unauthorized
Content-Type: application/json; charset=utf-8
Content-Length: 38
{"statusCode": 401, "key": "LOGIN.ERROR"}
|
Eine erfolgreiche Anmeldung setzt den Cookie, den [curl] in [cookies.txt] speichert:
| $ curl -i -c cookies.txt --json @curl/login-admin.json http://localhost:8080/api/auth/login
HTTP/1.1 200 OK
Set-Cookie: rdvmedecins_jwt=eyJhbGciOiJIUzI1NiIs...; Max-Age=7200; Path=/api; Expires=Mon, 28 Sep 2026 12:49:12 GMT; HttpOnly; SameSite=Strict
Content-Type: application/json; charset=utf-8
Content-Length: 55
{"login": "admin", "name": "Administrator", "role": "ADMIN"}
|
Mit diesem Cookie weiß der Server, wer wir sind:
| $ curl -i -b cookies.txt http://localhost:8080/api/auth/me
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 55
{"login": "admin", "name": "Administrator", "role": "ADMIN"}
|
Ein gefälschtes (oder abgelaufenes) Token führt zu einer abgelaufenen Sitzung, und der Server weist den Browser an, den Cookie zu löschen:
| $ curl -i -b "rdvmedecins_jwt=abc.def.ghi" http://localhost:8080/api/auth/me
HTTP/1.1 401 Unauthorized
Set-Cookie: rdvmedecins_jwt=; Path=/api; Expires=Thu, 01 Jan 1970 00:00:00 GMT
Content-Type: application/json; charset=utf-8
Content-Length: 49
{"statusCode": 401, "key": "ERRORS.SESSION_EXPIRED"}
|
8.6.2. Ärzte, Klienten, Terminkalender
Die Liste der Ärzte, wie ADMIN sie sieht (mit Logins):
| $ curl -i -b cookies.txt http://localhost:8080/api/doctors
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 282
[
{"id": 3, "version": 0, "title": "Melle", "firstName": "Sophie", "lastName": "DUPONT", "login": "dupont"},
{"id": 1, "version": 0, "title": "Mme", "firstName": "Marie", "lastName": "PELISSIER", "login": "pelissier"},
{"id": 2, "version": 0, "title": "Mr", "firstName": "Paul", "lastName": "TATOU", "login": "tatou"}
]
|
Der Terminkalender von Dr. PELISSIER für den 15. Januar 2030:
| $ curl -s -b cookies.txt "http://localhost:8080/api/schedule?doctorId=1&day=2030-01-15"
{
"doctor": {"id": 1, "version": 0, "title": "Mme", "firstName": "Marie", "lastName": "PELISSIER"},
"day": "2030-01-15",
"slots": [
{"id": 1, "startHour": 8, "startMinute": 0, "endHour": 8, "endMinute": 20, "free": true, "patient": null, "mine": false, "bookable": true, "appointmentId": null},
{"id": 2, "startHour": 8, "startMinute": 20, "endHour": 8, "endMinute": 40, "free": true, "patient": null, "mine": false, "bookable": true, "appointmentId": null},
{"id": 3, "startHour": 8, "startMinute": 40, "endHour": 9, "endMinute": 0, "free": true, "patient": null, "mine": false, "bookable": true, "appointmentId": null},
{"id": 4, "startHour": 9, "startMinute": 0, "endHour": 9, "endMinute": 20, "free": true, "patient": null, "mine": false, "bookable": true, "appointmentId": null},
{"id": 5, "startHour": 9, "startMinute": 20, "endHour": 9, "endMinute": 40, "free": true, "patient": null, "mine": false, "bookable": true, "appointmentId": null},
{"id": 6, "startHour": 9, "startMinute": 40, "endHour": 10, "endMinute": 0, "free": true, "patient": null, "mine": false, "bookable": true, "appointmentId": null},
{"id": 7, "startHour": 10, "startMinute": 0, "endHour": 10, "endMinute": 20, "free": true, "patient": null, "mine": false, "bookable": true, "appointmentId": null},
{"id": 8, "startHour": 10, "startMinute": 20, "endHour": 10, "endMinute": 40, "free": true, "patient": null, "mine": false, "bookable": true, "appointmentId": null},
{"id": 9, "startHour": 10, "startMinute": 40, "endHour": 11, "endMinute": 0, "free": true, "patient": null, "mine": false, "bookable": true, "appointmentId": null},
{"id": 10, "startHour": 11, "startMinute": 0, "endHour": 11, "endMinute": 20, "free": true, "patient": null, "mine": false, "bookable": true, "appointmentId": null},
{"id": 11, "startHour": 11, "startMinute": 20, "endHour": 11, "endMinute": 40, "free": true, "patient": null, "mine": false, "bookable": true, "appointmentId": null},
{"id": 12, "startHour": 11, "startMinute": 40, "endHour": 12, "endMinute": 0, "free": true, "patient": null, "mine": false, "bookable": true, "appointmentId": null}
],
"info": null
}
|
Ein Datum, das nicht existiert:
| $ curl -i -b cookies.txt "http://localhost:8080/api/schedule?doctorId=1&day=2030-02-30"
HTTP/1.1 400 Bad Request
Content-Type: application/json; charset=utf-8
Content-Length: 46
{"statusCode": 400, "key": "ERRORS.INVALID_DATE"}
|
8.6.3. Termine
ADMIN reserviert das Zeitfenster 3 für Patient Nr. 2 (Alice DURAND). Der Body der Anfrage:
| { "day": "2030-01-15", "slotId": 3, "clientId": 2 }
|
| $ curl -i -b cookies.txt --json @curl/appointment-admin.json http://localhost:8080/api/appointments
HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8
Content-Length: 51
{"id": 2, "day": "2030-01-15", "slotId": 3, "clientId": 2}
|
Der Terminkalender zeigt diesen Termin nun an, zusammen mit dem Namen des Patienten und der Angabe, wie er storniert werden kann ([appointmentId]):
| $ curl -s -b cookies.txt "http://localhost:8080/api/schedule?doctorId=1&day=2030-01-15"
{
"doctor": {"id": 1, "version": 0, "title": "Mme", "firstName": "Marie", "lastName": "PELISSIER"},
"day": "2030-01-15",
"slots": [
{"id": 1, "startHour": 8, "startMinute": 0, "endHour": 8, "endMinute": 20, "free": true, "patient": null, "mine": false, "bookable": true, "appointmentId": null},
{"id": 2, "startHour": 8, "startMinute": 20, "endHour": 8, "endMinute": 40, "free": true, "patient": null, "mine": false, "bookable": true, "appointmentId": null},
{"id": 3, "startHour": 8, "startMinute": 40, "endHour": 9, "endMinute": 0, "free": false, "patient": {"title": "Mme", "firstName": "Alice", "lastName": "DURAND"}, "mine": false, "bookable": false, "appointmentId": 2},
{"id": 4, "startHour": 9, "startMinute": 0, "endHour": 9, "endMinute": 20, "free": true, "patient": null, "mine": false, "bookable": true, "appointmentId": null},
{"id": 5, "startHour": 9, "startMinute": 20, "endHour": 9, "endMinute": 40, "free": true, "patient": null, "mine": false, "bookable": true, "appointmentId": null},
{"id": 6, "startHour": 9, "startMinute": 40, "endHour": 10, "endMinute": 0, "free": true, "patient": null, "mine": false, "bookable": true, "appointmentId": null},
{"id": 7, "startHour": 10, "startMinute": 0, "endHour": 10, "endMinute": 20, "free": true, "patient": null, "mine": false, "bookable": true, "appointmentId": null},
{"id": 8, "startHour": 10, "startMinute": 20, "endHour": 10, "endMinute": 40, "free": true, "patient": null, "mine": false, "bookable": true, "appointmentId": null},
{"id": 9, "startHour": 10, "startMinute": 40, "endHour": 11, "endMinute": 0, "free": true, "patient": null, "mine": false, "bookable": true, "appointmentId": null},
{"id": 10, "startHour": 11, "startMinute": 0, "endHour": 11, "endMinute": 20, "free": true, "patient": null, "mine": false, "bookable": true, "appointmentId": null},
{"id": 11, "startHour": 11, "startMinute": 20, "endHour": 11, "endMinute": 40, "free": true, "patient": null, "mine": false, "bookable": true, "appointmentId": null},
{"id": 12, "startHour": 11, "startMinute": 40, "endHour": 12, "endMinute": 0, "free": true, "patient": null, "mine": false, "bookable": true, "appointmentId": null}
],
"info": null
}
|
Noch einmal versuchen: Der Patient hat bereits einen bevorstehenden Termin. Ein Termin in der Vergangenheit wird ebenfalls abgelehnt:
| $ curl -i -b cookies.txt --json @curl/appointment-admin.json http://localhost:8080/api/appointments
HTTP/1.1 409 Conflict
Content-Type: application/json; charset=utf-8
Content-Length: 66
{"statusCode": 409, "key": "ERRORS.PATIENT_HAS_UPCOMING_APPOINTMENT"}
|
| $ curl -i -b cookies.txt --json @curl/appointment-past.json http://localhost:8080/api/appointments
HTTP/1.1 409 Conflict
Content-Type: application/json; charset=utf-8
Content-Length: 43
{"statusCode": 409, "key": "ERRORS.PAST_DATE"}
|
Ein gewöhnliches HTML-Formular (hier simuliert durch [-d], das [application/x-www-form-urlencoded] sendet) wird abgelehnt:
| $ curl -i -b cookies.txt -d "day=2030-01-15&slotId=4&clientId=2" http://localhost:8080/api/appointments
HTTP/1.1 415 Unsupported Media Type
Content-Type: application/json; charset=utf-8
Content-Length: 47
{"statusCode": 415, "key": "ERRORS.JSON_REQUIRED"}
|
8.6.4. Die Sicht eines Patienten
Sie melden sich ab und dann als [martin] an:
| $ curl -i -b cookies.txt -c cookies.txt --json @curl/empty.json http://localhost:8080/api/auth/logout
HTTP/1.1 200 OK
Set-Cookie: rdvmedecins_jwt=; Path=/api; Expires=Thu, 01 Jan 1970 00:00:00 GMT
Content-Type: application/json; charset=utf-8
Content-Length: 2
{}
|
| $ curl -s -c cookies-martin.txt --json @curl/login-martin.json http://localhost:8080/api/auth/login
{"login": "martin", "name": "Jean MARTIN", "role": "USER"}
|
Derselbe Terminkalender aus Sicht eines Patienten: Das Zeitfenster 3 ist belegt (["free": false]), aber ["patient"] entspricht [null]: Alices Name, DURAND, wurde nicht gesendet:
| $ curl -s -b cookies-martin.txt "http://localhost:8080/api/schedule?doctorId=1&day=2030-01-15"
{
"doctor": {"id": 1, "version": 0, "title": "Mme", "firstName": "Marie", "lastName": "PELISSIER"},
"day": "2030-01-15",
"slots": [
{"id": 1, "startHour": 8, "startMinute": 0, "endHour": 8, "endMinute": 20, "free": true, "patient": null, "mine": false, "bookable": true, "appointmentId": null},
{"id": 2, "startHour": 8, "startMinute": 20, "endHour": 8, "endMinute": 40, "free": true, "patient": null, "mine": false, "bookable": true, "appointmentId": null},
{"id": 3, "startHour": 8, "startMinute": 40, "endHour": 9, "endMinute": 0, "free": false, "patient": null, "mine": false, "bookable": false, "appointmentId": null},
{"id": 4, "startHour": 9, "startMinute": 0, "endHour": 9, "endMinute": 20, "free": true, "patient": null, "mine": false, "bookable": true, "appointmentId": null},
{"id": 5, "startHour": 9, "startMinute": 20, "endHour": 9, "endMinute": 40, "free": true, "patient": null, "mine": false, "bookable": true, "appointmentId": null},
{"id": 6, "startHour": 9, "startMinute": 40, "endHour": 10, "endMinute": 0, "free": true, "patient": null, "mine": false, "bookable": true, "appointmentId": null},
{"id": 7, "startHour": 10, "startMinute": 0, "endHour": 10, "endMinute": 20, "free": true, "patient": null, "mine": false, "bookable": true, "appointmentId": null},
{"id": 8, "startHour": 10, "startMinute": 20, "endHour": 10, "endMinute": 40, "free": true, "patient": null, "mine": false, "bookable": true, "appointmentId": null},
{"id": 9, "startHour": 10, "startMinute": 40, "endHour": 11, "endMinute": 0, "free": true, "patient": null, "mine": false, "bookable": true, "appointmentId": null},
{"id": 10, "startHour": 11, "startMinute": 0, "endHour": 11, "endMinute": 20, "free": true, "patient": null, "mine": false, "bookable": true, "appointmentId": null},
{"id": 11, "startHour": 11, "startMinute": 20, "endHour": 11, "endMinute": 40, "free": true, "patient": null, "mine": false, "bookable": true, "appointmentId": null},
{"id": 12, "startHour": 11, "startMinute": 40, "endHour": 12, "endMinute": 0, "free": true, "patient": null, "mine": false, "bookable": true, "appointmentId": null}
],
"info": null
}
|
Ein Patient hat keinen Zugriff auf die Klientenliste:
| $ curl -i -b cookies-martin.txt http://localhost:8080/api/clients
HTTP/1.1 403 Forbidden
Content-Type: application/json; charset=utf-8
Content-Length: 43
{"statusCode": 403, "key": "ERRORS.FORBIDDEN"}
|
Er reserviert für sich selbst (der Body enthält kein [clientId]), einmal, nicht zweimal:
| { "day": "2030-01-15", "slotId": 5 }
|
| $ curl -i -b cookies-martin.txt --json @curl/appointment-martin.json http://localhost:8080/api/appointments
HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8
Content-Length: 51
{"id": 3, "day": "2030-01-15", "slotId": 5, "clientId": 1}
|
| $ curl -i -b cookies-martin.txt --json @curl/appointment-martin-2.json http://localhost:8080/api/appointments
HTTP/1.1 409 Conflict
Content-Type: application/json; charset=utf-8
Content-Length: 55
{"statusCode": 409, "key": "SCHEDULE.ALREADY_BOOKED_INFO"}
|
Sein Bereich:
| $ curl -s -b cookies-martin.txt http://localhost:8080/api/my-area
{
"patient": {"title": "Mr", "firstName": "Jean", "lastName": "MARTIN"},
"appointments": [
{
"id": 3,
"day": "2030-01-15",
"slot": {"id": 5, "startHour": 9, "startMinute": 20, "endHour": 9, "endMinute": 40},
"doctor": {"id": 1, "version": 0, "title": "Mme", "firstName": "Marie", "lastName": "PELISSIER"}
}
]
}
|
Er kann den Termin eines anderen Patienten nicht stornieren. Der Server antwortet mit „nicht gefunden“, genau wie bei einem Termin, der nicht existiert: Er verrät nichts über die Termine anderer Patienten:
| $ curl -i -b cookies-martin.txt -X DELETE http://localhost:8080/api/appointments/2
HTTP/1.1 404 Not Found
Content-Type: application/json; charset=utf-8
Content-Length: 55
{"statusCode": 404, "key": "ERRORS.APPOINTMENT_NOT_FOUND"}
|
Seinen eigenen schon:
| $ curl -i -b cookies-martin.txt -X DELETE http://localhost:8080/api/appointments/3
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 2
{}
|
8.6.5. Die Sicht eines Arztes
Ohne [doctorId] erhält ein angemeldeter Arzt SEINEN EIGENEN Terminkalender mit allen Namen:
| $ curl -s -b cookies-pelissier.txt "http://localhost:8080/api/schedule?day=2030-01-15"
{
"doctor": {"id": 1, "version": 0, "title": "Mme", "firstName": "Marie", "lastName": "PELISSIER"},
"day": "2030-01-15",
"slots": [
{"id": 1, "startHour": 8, "startMinute": 0, "endHour": 8, "endMinute": 20, "free": true, "patient": null, "mine": false, "bookable": true, "appointmentId": null},
{"id": 2, "startHour": 8, "startMinute": 20, "endHour": 8, "endMinute": 40, "free": true, "patient": null, "mine": false, "bookable": true, "appointmentId": null},
{"id": 3, "startHour": 8, "startMinute": 40, "endHour": 9, "endMinute": 0, "free": false, "patient": {"title": "Mme", "firstName": "Alice", "lastName": "DURAND"}, "mine": false, "bookable": false, "appointmentId": 2},
{"id": 4, "startHour": 9, "startMinute": 0, "endHour": 9, "endMinute": 20, "free": true, "patient": null, "mine": false, "bookable": true, "appointmentId": null},
{"id": 5, "startHour": 9, "startMinute": 20, "endHour": 9, "endMinute": 40, "free": false, "patient": {"title": "Mr", "firstName": "Jean", "lastName": "MARTIN"}, "mine": false, "bookable": false, "appointmentId": 3},
{"id": 6, "startHour": 9, "startMinute": 40, "endHour": 10, "endMinute": 0, "free": true, "patient": null, "mine": false, "bookable": true, "appointmentId": null},
{"id": 7, "startHour": 10, "startMinute": 0, "endHour": 10, "endMinute": 20, "free": true, "patient": null, "mine": false, "bookable": true, "appointmentId": null},
{"id": 8, "startHour": 10, "startMinute": 20, "endHour": 10, "endMinute": 40, "free": true, "patient": null, "mine": false, "bookable": true, "appointmentId": null},
{"id": 9, "startHour": 10, "startMinute": 40, "endHour": 11, "endMinute": 0, "free": true, "patient": null, "mine": false, "bookable": true, "appointmentId": null},
{"id": 10, "startHour": 11, "startMinute": 0, "endHour": 11, "endMinute": 20, "free": true, "patient": null, "mine": false, "bookable": true, "appointmentId": null},
{"id": 11, "startHour": 11, "startMinute": 20, "endHour": 11, "endMinute": 40, "free": true, "patient": null, "mine": false, "bookable": true, "appointmentId": null},
{"id": 12, "startHour": 11, "startMinute": 40, "endHour": 12, "endMinute": 0, "free": true, "patient": null, "mine": false, "bookable": true, "appointmentId": null}
],
"info": null
}
|
Er verwaltet keine Ärzte:
| $ curl -i -b cookies-pelissier.txt --json @curl/doctor-add.json http://localhost:8080/api/doctors
HTTP/1.1 403 Forbidden
Content-Type: application/json; charset=utf-8
Content-Length: 43
{"statusCode": 403, "key": "ERRORS.FORBIDDEN"}
|
8.6.6. Ärzte und Klienten verwalten (ADMIN)
Ein Hinzufügen. Fehlt der Benutzername, ist der Standardwert der Name in Kleinbuchstaben; das Passwort ist der Benutzername:
| { "title": "Mme", "firstName": "Claire", "lastName": "LEROY" }
|
| $ curl -i -b cookies.txt --json @curl/doctor-add.json http://localhost:8080/api/doctors
HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8
Content-Length: 90
{"id": 4, "version": 1, "title": "Mme", "firstName": "Claire", "lastName": "LEROY", "login": "leroy"}
|
Ungültiger Body: Die Antwort listet den Fehler zu jedem Feld auf:
| { "title": "Dr", "firstName": "", "lastName": "A-LAST-NAME-FAR-TOO-LONG-FOR-THE-DB", "login": "Claire L" }
|
| $ curl -i -b cookies.txt --json @curl/doctor-invalid.json http://localhost:8080/api/doctors
HTTP/1.1 400 Bad Request
Content-Type: application/json; charset=utf-8
Content-Length: 218
{
"statusCode": 400,
"key": "ERRORS.INVALID_FORM",
"params": {"min": "6"},
"fields": {"login": "ERRORS.INVALID_LOGIN", "title": "ERRORS.INVALID_TITLE", "firstName": "ERRORS.FIRSTNAME_REQUIRED", "lastName": "ERRORS.LASTNAME_TOO_LONG"}
}
|
Ein Namensvetter: Beide betroffenen Felder werden markiert:
| $ curl -i -b cookies.txt --json @curl/doctor-duplicate.json http://localhost:8080/api/doctors
HTTP/1.1 409 Conflict
Content-Type: application/json; charset=utf-8
Content-Length: 151
{"statusCode": 409, "key": "ERRORS.DOCTOR_ALREADY_EXISTS", "fields": {"firstName": "ERRORS.DOCTOR_ALREADY_EXISTS", "lastName": "ERRORS.DOCTOR_ALREADY_EXISTS"}}
|
Eine Änderung. Die [version] ist die aus dem Datensatz gelesene (hier 1):
| { "title": "Mme", "firstName": "Claire", "lastName": "LEROY-MARTIN", "version": 1 }
|
| $ curl -i -b cookies.txt -X PUT --json @curl/doctor-edit.json http://localhost:8080/api/doctors/4
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 97
{"id": 4, "version": 2, "title": "Mme", "firstName": "Claire", "lastName": "LEROY-MARTIN", "login": "leroy"}
|
Der Datensatz hat nun Version 2. Würde dieselbe Änderung (mit Version 1) erneut gesendet, würde ein Datensatz überschrieben, der inzwischen von jemand anderem geändert wurde: Das optimistische Sperren verhindert dies:
| $ curl -i -b cookies.txt -X PUT --json @curl/doctor-edit.json http://localhost:8080/api/doctors/4
HTTP/1.1 409 Conflict
Content-Type: application/json; charset=utf-8
Content-Length: 51
{"statusCode": 409, "key": "ERRORS.CONCURRENT_UPDATE"}
|
Ein Arzt mit Terminen kann nicht gelöscht werden; die anderen schon:
| $ curl -i -b cookies.txt -X DELETE http://localhost:8080/api/doctors/1
HTTP/1.1 409 Conflict
Content-Type: application/json; charset=utf-8
Content-Length: 57
{"statusCode": 409, "key": "ERRORS.DOCTOR_HAS_APPOINTMENTS"}
|
| $ curl -i -b cookies.txt -X DELETE http://localhost:8080/api/doctors/4
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 2
{}
|
8.6.7. Ein Konto erstellen
Ohne Pass ist das unmöglich:
| $ curl -i --json @curl/registration.json http://localhost:8080/api/register
HTTP/1.1 403 Forbidden
Content-Type: application/json; charset=utf-8
Content-Length: 56
{"statusCode": 403, "key": "ERRORS.CAPTCHA_BEFORE_ACCOUNT"}
|
Zuerst lösen Sie ein CAPTCHA; der Server stellt in einem Cookie ein Token aus, das 15 Minuten gültig ist:
| $ curl -i -c cookies-registration.txt --json @curl/captcha-test.json http://localhost:8080/api/register/access
HTTP/1.1 200 OK
Set-Cookie: rdvmedecins_registration=60f5fa35-f939-4c87-b5a2-7c2f38054cc3; Max-Age=900; Path=/api/register; Expires=Mon, 28 Sep 2026 11:04:12 GMT; HttpOnly; SameSite=Strict
Content-Type: application/json; charset=utf-8
Content-Length: 2
{}
|
| $ curl -s -b cookies-registration.txt http://localhost:8080/api/register/access
{"valid": true}
|
Die Passwortbestätigung muss identisch sein:
| $ curl -i -b cookies-registration.txt --json @curl/registration-confirmation.json http://localhost:8080/api/register
HTTP/1.1 400 Bad Request
Content-Type: application/json; charset=utf-8
Content-Length: 98
{"statusCode": 400, "key": "ERRORS.INVALID_FORM", "fields": {"confirmation": "ERRORS.PASSWORDS_DIFFER"}}
|
| { "title": "Mme", "firstName": "Julie", "lastName": "BERNARD", "login": "jbernard", "password": "secret1", "confirmation": "secret1" }
|
| $ curl -i -b cookies-registration.txt -c cookies-registration.txt --json @curl/registration.json http://localhost:8080/api/register
HTTP/1.1 201 Created
Set-Cookie: rdvmedecins_registration=; Path=/api/register; Expires=Thu, 01 Jan 1970 00:00:00 GMT
Content-Type: application/json; charset=utf-8
Content-Length: 20
{"login": "jbernard"}
|
Der Pass wurde verbraucht: Mit ihm kann kein zweites Konto erstellt werden:
| $ curl -i -b cookies-registration.txt --json @curl/registration.json http://localhost:8080/api/register
HTTP/1.1 403 Forbidden
Content-Type: application/json; charset=utf-8
Content-Length: 56
{"statusCode": 403, "key": "ERRORS.CAPTCHA_BEFORE_ACCOUNT"}
|
8.6.8. Ihr Konto verwalten
Die neue Patientin meldet sich an und liest ihren Kontodatensatz:
| $ curl -s -b cookies-jbernard.txt http://localhost:8080/api/my-account
{"title": "Mme", "firstName": "Julie", "lastName": "BERNARD", "login": "jbernard", "version": 1}
|
Eine Änderung erfordert das aktuelle Passwort. Der Server stellt ein neues Token aus, das den neuen Namen enthält:
| { "title": "Mme", "firstName": "Julie", "lastName": "BERNARD-DUVAL", "login": "jbernard", "currentPassword": "secret1", "version": 1 }
|
| $ curl -i -b cookies-jbernard.txt -c cookies-jbernard.txt -X PUT --json @curl/my-account.json http://localhost:8080/api/my-account
HTTP/1.1 200 OK
Set-Cookie: rdvmedecins_jwt=eyJhbGciOiJIUzI1NiIs...; Max-Age=7200; Path=/api; Expires=Mon, 28 Sep 2026 12:49:13 GMT; HttpOnly; SameSite=Strict
Content-Type: application/json; charset=utf-8
Content-Length: 63
{"login": "jbernard", "name": "Julie BERNARD-DUVAL", "role": "USER"}
|
Das Löschen des Kontos löscht auch den Cookie:
| $ curl -i -b cookies-jbernard.txt -c cookies-jbernard.txt -X DELETE --json @curl/my-account-delete.json http://localhost:8080/api/my-account
HTTP/1.1 200 OK
Set-Cookie: rdvmedecins_jwt=; Path=/api; Expires=Thu, 01 Jan 1970 00:00:00 GMT
Content-Type: application/json; charset=utf-8
Content-Length: 2
{}
|
| $ curl -i -b cookies-jbernard.txt http://localhost:8080/api/auth/me
HTTP/1.1 401 Unauthorized
Content-Type: application/json; charset=utf-8
Content-Length: 47
{"statusCode": 401, "key": "ERRORS.AUTH_REQUIRED"}
|
8.6.9. Einige Fehler
Eine unbekannte Route, ein Body, der kein gültiges JSON ist:
| $ curl -i -b cookies-martin.txt http://localhost:8080/api/does-not-exist
HTTP/1.1 404 Not Found
Content-Type: application/json; charset=utf-8
Content-Length: 43
{"statusCode": 404, "key": "ERRORS.NOT_FOUND"}
|
| $ curl -i -b cookies.txt -H "Content-Type: application/json" -d "{not json" http://localhost:8080/api/appointments
HTTP/1.1 400 Bad Request
Content-Type: application/json; charset=utf-8
Content-Length: 45
{"statusCode": 400, "key": "ERRORS.BAD_REQUEST"}
|
Wir wissen nun alles Nötige über den Server, um unseren Client zu schreiben.