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]. Dies ist der [NestJS]-Server 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 nur 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 für einen Client-Entwickler: 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 ausführlich kommentiert, für den neugierigen Leser.

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 Clients 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. Im Terminkalender sehen sie die Namen anderer Patienten nicht

Die Demokonten 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 Clients) 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 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-Datei ausführen); an 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.

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.
# 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 Angular-Client erreicht ihn über den Proxy von ng serve)
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 von JWT-Tokens - MUSS geändert werden
# in der Produktion (ein langer Zufallsstring, 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 niemals über eine unverschlüsselte Verbindung gesendet.
COOKIE_SECURE=false

# -----------------------------------------------------------------------
# Schutz vor Bots
# -----------------------------------------------------------------------
# Login: Anzahl erlaubter 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 ebenfalls gesperrt, wenn sie 5-mal
# mehr Fehlversuche ansammelt, alle Logins zusammengenommen)
LOGIN_BLOCK_MINUTES=15
# Anlegen von Kundenkonten: maximale Anzahl pro Stunde angelegter 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 lässt sich das Bild nicht "lesen").
# In der Produktion LEER lassen.
CAPTCHA_TEST=

# -----------------------------------------------------------------------
# Produktion
# -----------------------------------------------------------------------
# Ordner des kompilierten Angular-Clients, der von diesem Server ausgeliefert wird (Standard: client/)
# CLIENT_DIR=client
# auf true setzen, wenn der Server hinter einem Proxy (nginx...) steht
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 (Sperre nach mehreren fehlgeschlagenen Anmeldeversuchen, Anzahl der pro Stunde erstellten Konten);
  • Zeile 51: der CAPTCHA-Testmodus. Die Anmeldeseite verlangt, dass die 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 tragen 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. Start.

npm run start:dev

Die Konsole zeigt an (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 gestoppt, falsches Passwort), wird der Server sofort mit einer Fehlermeldung zur Verbindung beendet.

7.3. Antwortformat

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

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 Nachricht. Der Server gibt nie Text zur Anzeige 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): Parameter der Nachricht ([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], mit Benutzername, Passwort und CAPTCHA-Antwort. Als Gegenleistung legt der Server im Browser einen Cookie ab, der 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 diesen Cookie nicht lesen. Ein in die Seite eingeschleustes schädliches 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 sendet ihn nur bei Anfragen an die API mit;
  • [SameSite=Strict]: Der Browser sendet dieses Token nur bei Anfragen mit, die VON einer Seite dieser Website ausgehen. Eine schädliche 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, zeitgleich mit dem Ablauf des Tokens.

Der Browser sendet diesen Cookie dann automatisch bei jeder Anfrage an [/api] mit. Der [Angular] -Client muss sich daher um nichts kümmern, um sich zu authentifizieren, sofern seine Seiten und die API denselben Ursprung haben (dasselbe Protokoll, derselbe Rechner, derselbe Port). Das ist die Aufgabe des Proxys im [Angular]-Entwicklungsserver (siehe Beispiel 22) und in der Produktion die des Servers selbst (siehe Kapitel „Bereitstellung“).

Eine zweite Absicherung gegen CSRF-Angriffe: Der Server weist (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 den 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 ignoriert bei einem USER); 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 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 verfügbar?
  • [patient]: der Patient des Termins. Für einen angemeldeten Patienten ist dies gleich [null], außer bei SEINEN EIGENEN Terminen: 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, für einen Patienten, kein bevorstehender Termin)?
  • [appointmentId]: Gesetzt, 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] des Servers 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" }

Die Befehle werden in einer Konsole eingegeben, die im Verzeichnis [rdvmedecins-nestjs-json] geöffnet ist. Einige Optionen von [curl]:

  • [-i]: zeigt zusätzlich die Antwort-Header an; [-s]: ohne Fortschrittsanzeige;
  • [--json @file]: sendet den Inhalt der Datei per POST, 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]: speichert die empfangenen Cookies in dieser Datei; [-b cookies.txt]: sendet sie zurück. So „bleibt [curl] angemeldet“ von einem Befehl zum nächsten, genau wie ein Browser.

Unter [PowerShell] müssen Sie [curl.exe] und nicht [curl] eingeben (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.

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: 11304

{"id": "e33886ae-1a8b-4302-8cbc-cd7015e82f1f", "svg": "<svg xmlns=\"http://www.w3.org/2000/svg\" width=\"150..."}

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

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 den Cookie, den [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, den 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, 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"}
]

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 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 Sie 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 gewöhnliches 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. Aus 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: Zeitfenster 3 ist belegt (["free": false]), aber ["patient"] entspricht [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 Client-Liste:

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. 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:

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 Clients 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 markiert:

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 aus dem Datensatz gelesene (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. Das erneute Senden derselben Änderung (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"}

Zuerst lösen Sie ein CAPTCHA; der Server stellt in einem Cookie ein Token aus, das 15 Minuten gültig ist:

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=73a037d1-78f2-4e8e-a3a5-b6660a4f7fd5; 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: Er kann nicht für ein zweites Konto verwendet 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 ihren Kontodatensatz:

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

Für eine Änderung ist das aktuelle Passwort erforderlich. 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 den 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, was wir über den Server wissen müssen, um unseren Client zu schreiben.