Skip to content

7. Der RdvMedecins-Server, eine Blackbox

Die Beispiele 22 bis 25 sowie 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 erzeugen, sondern JSON-Antworten liefern. 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 allein seine API – das heißt 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 Serverteam 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 fragt ihn mit [curl] ab.

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 Klienten verwalten
[DOCTOR]
Ärzte ([pelissier], [tatou], [dupont])
Termine für alle Patienten vereinbaren und stornieren; alle Namen in den Terminkalendern sehen
[USER]
Patienten ([martin], [durand], [bistrou], [german])
Termine für sich selbst buchen; ihre Termine stornieren; ihr Konto verwalten. In einem Terminkalender sehen sie die Namen anderer Patienten nicht

Die Demo-Konten verwenden ihren Login als Passwort. Die Verwaltungsregeln werden vom Server unabhängig vom Client überprü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 nur zu einem Konto;
  • ein Arzt mit Terminen kann nicht gelöscht werden;
  • ein Datensatz, der zwischenzeitlich 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 wird 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 in [HeidiSQL] aus (Menü Datei / SQL ausführen); in der Kommandozeile:

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.

2. Bibliotheken. In einem Konsolenfenster, das im Ordner [rdvmedecins-nestjs-json] geöffnet ist:

npm install

3. Konfiguration. Kopieren Sie die Datei [.env.example] nach [.env] (unter [Windows]: [copy .env.example .env]) und ändern Sie sie dann:

# -----------------------------------------------------------------------
# Beispielkonfigurationsdatei.
# Diese Datei nach [.env] kopieren und dann die Werte an den eigenen Rechner anpassen.
# Die Datei [.env] darf niemals weitergegeben oder committet werden (Passwörter).
# -----------------------------------------------------------------------

# Listening-Port des JSON-Servers (der React-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: gibt in der Konsole die an MySQL gesendeten SQL-Abfragen aus
DB_LOGGING=false

# -----------------------------------------------------------------------
# Authentifizierung
# -----------------------------------------------------------------------
# Geheimer Schlüssel zum Signieren/Prüfen der JWT-Token - MUSS geändert werden
# in der Produktion (eine lange Zufallszeichenkette, 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 den Token trägt, hat dieselbe Lebensdauer.
JWT_EXPIRES_IN_SECONDS=7200
# in der Produktion auf true setzen (per HTTPS ausgelieferte Website): Das Authentifizierungs-
# Cookie wird dann niemals über eine unverschlüsselte Verbindung gesendet.
COOKIE_SECURE=false

# -----------------------------------------------------------------------
# Schutz vor Bots
# -----------------------------------------------------------------------
# Login: Anzahl der Fehlversuche (falsches CAPTCHA oder Passwort), die für
# denselben Login von derselben IP-Adresse erlaubt sind, bevor dieses Paar gesperrt wird...
LOGIN_MAX_FAILURES=5
# ... für diese Dauer (eine IP-Adresse wird auch gesperrt, wenn sie das
# Fünffache an Fehlversuchen ansammelt, alle Logins zusammengenommen)
LOGIN_BLOCK_MINUTES=15
# Anlegen von Kundenkonten: maximale Anzahl der pro Stunde angelegten Konten
# von derselben IP-Adresse. In einem Schulungsraum gehen oft alle Rechner
# über dieselbe Adresse nach außen: 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 (man kann das Bild in einer Konsole nicht „lesen“).
# In der Produktion LEER lassen.
CAPTCHA_TEST=

# -----------------------------------------------------------------------
# Produktion
# -----------------------------------------------------------------------
# Ordner des kompilierten React-Clients, der von diesem Server ausgeliefert wird (Standard: client/)
# CLIENT_DIR=client
# auf true setzen, wenn sich der Server hinter einem Proxy befindet (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 Authentifizierungstoken signiert;
  • Zeilen 38–45: Schutzmaßnahmen gegen Bots (Sperre nach mehreren fehlgeschlagenen Anmeldeversuchen, Anzahl der pro Stunde erstellten Konten);
  • Zeile 51: CAPTCHA-Testmodus. Die Anmeldeseite verlangt, dass Sie die Zeichen aus einem Bild eintippen, was von einer Konsole aus unmöglich ist. Hat diese Variable einen Wert, wird dieser Wert als Antwort auf jedes CAPTCHA akzeptiert, ganz wie die „Testschlüssel“, die [Google] für sein [reCAPTCHA] bereitstellt. Geben Sie für die Tests mit [curl] in diesem Kapitel [CAPTCHA_TEST=test] ein. Lassen Sie sie in der Produktion LEER;
  • Zeilen 57–59: zwei Einstellungen für die Produktion (siehe Kapitel „Deployment“).

4. Start.

npm run start:dev

Die Konsole zeigt (Auszug):

1
2
3
4
5
6
7
8
[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), stoppt der Server sofort mit einer Verbindungsfehlermeldung.

7.3. Antwortformat

Alle URLs beginnen mit [/api]. Eine erfolgreiche Anfrage erhält einen 2xx-Statuscode und im Body die angeforderten Daten im JSON-Format. Eine abgelehnte Anfrage erhält einen 4xx- oder 5xx-Code und im Body einen Fehler, der IMMER dasselbe Format hat:

1
2
3
4
5
6
{
  "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 anzuzeigenden Text zurück: 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]

7.4. Authentifizierung

Der Client authentifiziert sich mit [POST /api/auth/login], unter Angabe von Benutzername, Passwort und CAPTCHA-Antwort. Als Gegenleistung 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 bösartiges Skript, das möglicherweise in die Seite eingeschleust wurde, 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 Anfragen an die API bei;
  • [SameSite=Strict]: Der Browser fügt dieses Token nur Anfragen bei, 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 Token.

Der Browser sendet dieses Cookie dann automatisch mit jeder Anfrage an [/api]. Der [React] -Client muss daher nichts unternehmen, um sich zu authentifizieren, sofern seine Seiten und die API denselben Ursprung haben (gleiches Protokoll, gleicher Rechner, gleicher Port). Das ist die Aufgabe des Proxys des Entwicklungsservers [Vite] (siehe Beispiel 22) und in der Produktion des Servers selbst (siehe Kapitel „Deployment“).

Eine zweite Schutzmaßnahme gegen CSRF-Angriffe: Der Server lehnt (415) jede POST-Anfrage ab, deren Body 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 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 das 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 des Terminkalenders ([GET /api/schedule]) beschreibt ein Zeitfenster UND das, was der angemeldete Benutzer damit tun darf:

1
2
3
4
{ "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 frei?
  • [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, ohne bevorstehenden 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, obwohl er es nicht sollte), würde der Server bei der Buchung alles noch einmal prüfen.

7.6. Die API mit curl abfragen

Der Ordner [curl] auf dem Server enthält die JSON-Bodys der Anfragen 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 und nicht [curl] (das dort auf einen anderen Befehl verweist). Die etwas langen JSON-Antworten 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):

1
2
3
4
5
6
7
$ 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: 11528

{"id": "be956764-1c67-4d23-a744-d0c2cebbb791", "svg": "<svg xmlns=\"http://www.w3.org/2000/svg\" width=\"150..."}

Ohne Token liefert eine geschützte URL eine 401-Antwort:

1
2
3
4
5
6
$ 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:

1
2
3
4
5
6
$ 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"}}
1
2
3
4
5
6
$ 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] in [cookies.txt] speichert:

1
2
3
4
5
6
7
$ 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:

1
2
3
4
5
6
$ 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:

1
2
3
4
5
6
7
$ 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, 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:

1
2
3
4
5
6
$ 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 das Zeitfenster 3 für Patient Nr. 2 (Alice DURAND). Der Body der Anfrage:

{ "day": "2030-01-15", "slotId": 3, "clientId": 2 }
1
2
3
4
5
6
$ 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 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
}

Versuchen wir es erneut: Der Patient hat bereits einen bevorstehenden Termin. Ein Termin in der Vergangenheit wird ebenfalls abgelehnt:

1
2
3
4
5
6
$ 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"}
1
2
3
4
5
6
$ 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 standardmäßiges HTML-Formular (hier simuliert durch [-d], das [application/x-www-form-urlencoded] sendet) wird abgelehnt:

1
2
3
4
5
6
$ 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. Die Sicht eines Patienten

Sie melden sich ab und dann als [martin] an:

1
2
3
4
5
6
7
$ 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"] ist gleich [null]: Der Name von Alice, 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:

1
2
3
4
5
6
$ 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 bucht für sich selbst (der Body enthält kein [clientId]), einmal, nicht zweimal:

{ "day": "2030-01-15", "slotId": 5 }
1
2
3
4
5
6
$ 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}
1
2
3
4
5
6
$ 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:

1
2
3
4
5
6
$ 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:

1
2
3
4
5
6
$ 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. 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:

1
2
3
4
5
6
$ 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. Ärzte und Klienten verwalten (ADMIN)

Ein Hinzufügen. Fehlt der Login, ist der Standardwert der Name in Kleinbuchstaben; das Passwort ist der Login:

{ "title": "Mme", "firstName": "Claire", "lastName": "LEROY" }
1
2
3
4
5
6
$ 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 gekennzeichnet:

1
2
3
4
5
6
$ 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, die aus dem Datensatz gelesen wurde (hier 1):

{ "title": "Mme", "firstName": "Claire", "lastName": "LEROY-MARTIN", "version": 1 }
1
2
3
4
5
6
$ 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 die Version 2. Dieselbe Änderung erneut abzusenden (mit Version 1) würde einen Datensatz überschreiben, der inzwischen von jemand anderem geändert wurde: Das optimistische Sperren verhindert dies:

1
2
3
4
5
6
$ 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:

1
2
3
4
5
6
$ 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"}
1
2
3
4
5
6
$ 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 Pass ist es unmöglich:

1
2
3
4
5
6
$ 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"}

Zunächst lösen Sie ein CAPTCHA; der Server stellt ein Token aus, 15 Minuten gültig, in einem Cookie:

1
2
3
4
5
6
7
$ 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=fd231085-46dc-4a97-bc61-ea84494ee3c2; 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:

1
2
3
4
5
6
$ 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" }
1
2
3
4
5
6
7
$ 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 verwendet: Mit ihm kann kein zweites Konto erstellt werden:

1
2
3
4
5
6
$ 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. Das eigene Konto verwalten

Die neue Patientin meldet sich an und liest ihre Patientenakte:

$ curl -s -b cookies-jbernard.txt http://localhost:8080/api/my-account
{"title": "Mme", "firstName": "Julie", "lastName": "BERNARD", "login": "jbernard", "version": 1}

Jede Ä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 }
1
2
3
4
5
6
7
$ 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:

1
2
3
4
5
6
7
$ 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

{}
1
2
3
4
5
6
$ 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:

1
2
3
4
5
6
$ 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"}
1
2
3
4
5
6
$ 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.