7. Der RdvMedecins-Server, eine Blackbox
Die Beispiele 17 bis 20 und anschließend die Fallstudie interagieren mit einem Server: dem JSON-Server der Anwendung [RdvMedecins]. Es ist der [NestJS]-Server aus der vorherigen Lektion, dessen Controller keine HTML-Seiten mehr generieren, sondern JSON-Antworten erzeugen. Seine Geschäfts- und Datenzugriffsschichten bleiben unverändert.
In diesem Kurs ist dieser Server eine Blackbox: Wir müssen nicht wissen, wie er geschrieben ist. Wichtig ist nur seine API – also die Liste der HTTP-Anfragen, die er akzeptiert, und der Antworten, die er zurückgibt. Das ist die typische Situation eines Client-Entwicklers: Die API ist ein Vertrag, und das Server-Team kann hinter diesem Vertrag ändern, was es will. Sein Quellcode wird mitgeliefert (Ordner [rdvmedecins-nestjs-json]) und ist für den neugierigen Leser ausführlich kommentiert.
Dieses Kapitel erklärt, wie der Server installiert wird, beschreibt seine API und befragt ihn mit [curl].
7.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 Kunden verwalten |
[DOCTOR] | Ärzte ([pelissier], [tatou], [dupont]) | Termine für alle Patienten vereinbaren und stornieren; alle Namen in den Terminkalendern einsehen |
[USER] | Patienten ([martin], [durand], [bistrou], [german]) | Termine für sich selbst buchen; ihre Termine stornieren; ihre Konten verwalten. In einem Terminkalender sehen sie die Namen anderer Patienten nicht |
Die Demo-Konten verwenden ihren Login als Passwort. Die Verwaltungsregeln werden vom Server geprüft, unabhängig vom Client:
- keine Termine in der Vergangenheit;
- nur ein bevorstehender Termin pro Patient;
- ein Zeitfenster kann pro Tag nur einmal gebucht werden;
- zwei Ärzte (oder zwei Kunden) dürfen nicht dieselben Vor- und Nachnamen haben; ein Login gehört nur zu 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.
7.2. Installation
Sie benötigen [Node.js] und einen [MySQL] -Server (oder [MariaDB]): Ihre Installation ist im Anhang beschrieben.
1. Die Datenbank. Das Skript [database/dbrdvmedecins2.sql] erstellt die Datenbank [dbrdvmedecins2], ihre Tabellen und ihre Beispieldaten. Mit [Laragon] führen Sie es aus [HeidiSQL] heraus aus (Menü Datei / SQL-Datei ausführen); auf der Kommandozeile:
mysql -u root -p < database/dbrdvmedecins2.sql
Das Skript geht immer von einer leeren Datenbank aus: Sie können es erneut ausführen, um die ursprünglichen Daten wiederherzustellen.
2. Bibliotheken. In einer Konsole, die im Ordner [rdvmedecins-nestjs-json] geöffnet ist:
3. Konfiguration. Kopieren Sie die Datei [.env.example] nach [.env] (unter [Windows]: [copy .env.example .env]) und ändern Sie sie dann:
| # -----------------------------------------------------------------------
# Beispielkonfigurationsdatei.
# 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 (der Vue.js-Client erreicht ihn über den Vite-Proxy)
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/Verifizieren 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 (Site über HTTPS ausgeliefert): Das Authentifizierungs-
# Cookie wird dann niemals über eine unverschlüsselte Verbindung gesendet.
COOKIE_SECURE=false
# -----------------------------------------------------------------------
# Schutz vor Bots
# -----------------------------------------------------------------------
# Login: Anzahl der erlaubten 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 auch gesperrt, wenn sie
# 5-mal mehr Fehlversuche ansammelt, alle Logins zusammengenommen)
LOGIN_BLOCK_MINUTES=15
# Anlegen von Kundenkonten: maximale Anzahl der pro Stunde angelegten 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 (das Bild lässt sich in einer Konsole nicht "lesen").
# In der Produktion LEER lassen.
CAPTCHA_TEST=
# -----------------------------------------------------------------------
# Produktion
# -----------------------------------------------------------------------
# Ordner des kompilierten Vue.js-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, der die Authentifizierungs-Token signiert;
- Zeilen 38–45: Schutzmaßnahmen gegen Bots (Sperrung nach mehreren fehlgeschlagenen Anmeldeversuchen, Anzahl der pro Stunde erstellten Konten);
- Zeile 51: der CAPTCHA-Testmodus. Die Login-Seite verlangt, dass Benutzer die Zeichen aus einem Bild abtippen, 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. Für die Tests mit [curl] in diesem Kapitel geben Sie [CAPTCHA_TEST=test] ein. Lassen Sie sie in der Produktion LEER;
- Zeilen 57–59: zwei Einstellungen für die Produktion (siehe Kapitel „Bereitstellung“).
4. 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 Fehlermeldung zur Verbindung.
Alle URLs beginnen mit [/api]. Eine erfolgreiche Anfrage erhält einen 2xx-Statuscode und in ihrem Inhalt die angeforderten Daten im JSON-Format. Eine abgelehnte Anfrage erhält einen 4xx- oder 5xx-Statuscode und im Inhalt Daten im selben Format:
| {
"statusCode": 400,
"key": "ERRORS.INVALID_FORM",
"params": { "min": "6" },
"fields": { "lastName": "ERRORS.LASTNAME_REQUIRED", "password": "ERRORS.PASSWORD_TOO_SHORT" }
}
|
- [statusCode]: der HTTP-Code, im Inhalt wiederholt;
- [key]: der Übersetzungsschlüssel der Nachricht. Der Server gibt nie anzuzeigenden Text zurück: Er kennt die Sprache des Benutzers nicht mehr. Der Client übersetzt den Schlüssel mithilfe seiner Wörterbücher (siehe Beispiel 16);
- [params] (optional): die Parameter der Nachricht ([At least {min} characters.], [Try again in {minutes} minute(s).]);
- [fields] (optional): bei einem abgelehnten Formular der Fehler für jedes 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] |
7.4. Authentifizierung
Der Client authentifiziert sich mit [POST /api/auth/login], mit Benutzername, Passwort und CAPTCHA-Antwort. Im Gegenzug legt der Server ein Cookie im Browser ab, das ein signiertes JWT-Token enthält:
| Set-Cookie: rdvmedecins_jwt=eyJhbGciOiJIUzI1NiIs...; Max-Age=7200; Path=/api; HttpOnly; SameSite=Strict
|
Seine Attribute sind für die Sicherheit wichtig:
- [HttpOnly]: Der [JavaScript]-Code der Seite kann dieses 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 Browser fügt es nur in Anfragen an die API ein;
- [SameSite=Strict]: Der Browser fügt dieses Token nur in Anfragen ein, 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]: Es läuft nach zwei Stunden ab, zeitgleich mit dem Ablauf des Tokens.
Der Browser sendet dieses Cookie dann automatisch bei jeder Anfrage an [/api]. Der [Vue.js] -Client muss sich daher um nichts kümmern, um sich zu authentifizieren, vorausgesetzt, seine Seiten und die API haben denselben Ursprung (gleiches Protokoll, gleicher Rechner, gleicher Port). Dies ist die Aufgabe des [Vite]-Proxys während der Entwicklung (siehe Beispiel 17) und des Servers selbst in der Produktion (siehe Kapitel „Bereitstellung“).
Eine zweite Absicherung gegen CSRF-Angriffe: Der Server lehnt (415) jede POST-Anfrage ab, deren Inhalt nicht im JSON-Format vorliegt. Ein kompromittiertes HTML-Formular auf einer anderen Website kann kein JSON senden.
7.5. Die API
Methode | Adresse | Rollen | Gesendeter Inhalt / Antwortinhalt |
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 das Cookie |
GET | [/api/auth/me] | angemeldet | Antwort: [{ login, name, role }] |
GET | [/api/schedule?doctorId=&day=] | alle | Antwort: der Terminkalender (ohne doctorId: für einen 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 Datenblatt |
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 des Terminkalenders ([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. Für einen 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 (verfügbar, nicht in der Vergangenheit und, bei einem Patienten, kein bevorstehender Termin)?
- [appointmentId]: Gesetzt, wenn der Benutzer diesen Termin stornieren kann.
Der Server ENTSCHEIDET; der Client zeigt es an. Und selbst wenn ein Client schummeln würde (indem er eine Schaltfläche „Buchen“ anzeigt, obwohl er es nicht sollte), würde der Server bei der Buchung alles noch einmal prüfen.
7.6. Die API mit curl befragen
Der Ordner [curl] des Servers enthält die JSON-Anfrageinhalte dieses Kapitels, eine Datei pro Anfrage. Zum Beispiel [curl/login-admin.json]:
| { "login": "admin", "password": "admin", "captchaId": "-", "captcha": "test" }
|
Die 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 höher; 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 ein Browser.
Unter [PowerShell] müssen Sie [curl.exe] eingeben, nicht [curl] (das sich auf einen anderen Befehl bezieht). Die etwas langen Antworten im JSON-Format wurden für dieses Dokument formatiert, und die Header [Date], [ETag], [Connection], und [Keep-Alive] wurden entfernt.
7.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: 15076
{"id": "abf00f0c-60c0-4fde-9782-9906815e26a1", "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 das Cookie, das [curl] speichert in [cookies.txt]:
| $ 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, das 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"}
|
7.6.2. Ärzte, Clients, 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"}
]
|
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"}
|
7.6.3. Termine
ADMIN reserviert 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 nun diesen Termin an, zusammen mit dem Namen des Patienten und einer Anleitung zur Stornierung ([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
}
|
Versuchen Sie es erneut: 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"}
|
7.6.4. Aus 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: Zeitfenster 3 ist belegt (["free": false]), aber ["patient"] ist gleichbedeutend mit [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 Client-Liste:
| $ 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 dagegen 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
{}
|
7.6.5. Aus 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"}
|
7.6.6. Verwaltung von Ärzten und Clients (ADMIN)
Eine Hinzufügung. Fehlt der Benutzername, ist der Standardwert der Name in Kleinbuchstaben; das Passwort entspricht dem Benutzernamen:
| { "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 für jedes 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 Datenblatt 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
{}
|
7.6.7. Ein Konto erstellen
Ohne Berechtigungsnachweis ist es 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 ein Token aus, 15 Minuten gültig, in einem Cookie:
| $ 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=06be5557-401a-4bd4-ada2-277ca48fc74d; 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 Berechtigungsnachweis wurde verwendet: Er kann nicht für ein zweites Konto verwendet 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"}
|
7.6.8. Ihr Konto verwalten
Die neue Patientin meldet sich an und liest ihren Datensatz:
| $ 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 das 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"}
|
7.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.