Skip to content

8. Der RdvMedecins-Server als 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 Kurse [React], [Vue.js], [Angular] und [Flutter]: der Server des [NestJS]-Kurses, dessen Controller keine HTML-Seiten mehr erzeugen, sondern JSON-Antworten liefern. Leser dieser Kurse kennen dieses Kapitel bereits, das hier nahezu unverändert wiedergegeben wird; sie können sich allein auf den Abschnitt zur Authentifizierung konzentrieren, der erklärt, was sich für eine mobile Anwendung ändert.

In diesem Kurs ist dieser Server eine Blackbox: Sie müssen nicht wissen, wie er geschrieben ist. Allein seine API zählt, 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 beliebig ändern, was es möchte. Sein Quellcode wird für neugierige Leser mitgeliefert (Ordner [rdvmedecins-nestjs-json]) und ist ausführlich kommentiert.

Dieses Kapitel erklärt, wie der Server installiert wird, beschreibt seine API und fragt ihn mit [curl] ab.

8.1. Die Anwendung RdvMedecins

Die Anwendung verwaltet die Termine einer Arztpraxis. Sie kennt drei Rollen:

Rolle
Wer
Was sie dürfen
[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 einsehen
[USER]
Patienten ([martin], [durand], [bistrou], [german])
Termine für sich selbst buchen; ihre Termine stornieren; ihre Konten verwalten. In einem Terminkalender können sie die Namen anderer Patienten nicht sehen

Die Demo-Konten verwenden ihren Login als Passwort. Die Verwaltungsregeln werden unabhängig vom Client vom Server geprüft:

  • keine Termine in der Vergangenheit;
  • nur ein bevorstehender Termin pro Patient;
  • ein Zeitfenster kann pro Tag nur einmal gebucht werden;
  • zwei Ärzte (oder zwei Klienten) dürfen nicht denselben Vor- und Nachnamen haben; ein Login gehört nur zu einem Konto;
  • ein Arzt mit geplanten Terminen kann nicht gelöscht werden;
  • Ein Datensatz, der in der Zwischenzeit von jemand anderem geändert wurde, kann nicht überschrieben werden (optimistisches Sperren);
  • Einem Patienten wird nie der Name eines anderen Patienten zugewiesen.

8.2. Installation

Sie benötigen [Node.js] und einen [MySQL] -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); auf 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.

  1. Bibliotheken. In einem Konsolenfenster, das im Ordner [rdvmedecins-nestjs-json] geöffnet ist:
npm install
  1. Konfiguration. Kopieren Sie die Datei [.env.example] nach [.env] (unter [Windows]: [copy .env.example .env]) und ändern Sie sie anschließend:
# -----------------------------------------------------------------------
# Beispielhafte Konfigurationsdatei.
# Kopieren Sie diese Datei nach [.env] und passen Sie dann die Werte an Ihren Rechner an.
# Die Datei [.env] darf niemals weitergegeben oder committet werden (Passwörter).
# -----------------------------------------------------------------------

# Listening-Port des JSON-Servers
PORT=8080

# Verbindungsparameter zur 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). Der Cookie,
# der das Token trägt, hat dieselbe Lebensdauer.
JWT_EXPIRES_IN_SECONDS=7200
# in der Produktion auf true setzen (über HTTPS bereitgestellte Site): Der 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 Kursraum gehen oft alle Rechner über
# dieselbe Adresse ins Netz: bei Bedarf erhöhen.
REGISTRATION_MAX_PER_HOUR=10

# CAPTCHA-TESTMODUS: Wenn diese Variable einen Wert hat, wird dieser Wert
# als Antwort auf JEDES CAPTCHA akzeptiert. Praktisch, um die
# API mit curl abzufragen (ein Bild lässt sich in einer Konsole nicht "lesen").
# In der Produktion LEER lassen.
CAPTCHA_TEST=

# -----------------------------------------------------------------------
# Produktion
# -----------------------------------------------------------------------
# Ordner des kompilierten Web-Clients, der von diesem Server ausgeliefert wird (Standard: client/)
# CLIENT_DIR=client
# auf true setzen, wenn der Server hinter einem Proxy steht (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: Anti-Bot-Schutzmaßnahmen (Sperre nach mehreren fehlgeschlagenen Anmeldeversuchen, Anzahl der pro Stunde erstellten Konten);
  • Zeile 51: der Testmodus des CAPTCHA. Die Anmeldeseite verlangt, dass Benutzer die Zeichen aus einem Bild erneut 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. Tragen Sie für die Tests mit [curl] in diesem Kapitel [CAPTCHA_TEST=test] ein. Auch die automatisierten Tests, die die Screenshots für diesen Kurs erzeugt haben, verwenden diesen Wert. Lassen Sie sie in der Produktion LEER;
  • Zeilen 57–59: zwei Einstellungen für die Produktion (siehe Kapitel „Bereitstellung“).

  • 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 angehalten, falsches Passwort), beendet sich der Server sofort mit einer Verbindungsfehlermeldung.

8.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-Statuscode 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: 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 Zugang)
404
Nicht gefunden
[ERRORS.NOT_FOUND], [ERRORS.DOCTOR_NOT_FOUND], [ERRORS.APPOINTMENT_NOT_FOUND]...
409
Verletzung einer Geschäftsregel
[ERRORS.PAST_DATE], [ERRORS.SLOT_ALREADY_BOOKED], [ERRORS.LOGIN_TAKEN], [ERRORS.CONCURRENT_UPDATE]...
415
POST, der nicht im JSON-Format vorliegt
[ERRORS.JSON_REQUIRED]
429
Zu viele Versuche
[ERRORS.TOO_MANY_ATTEMPTS], [ERRORS.TOO_MANY_ACCOUNTS] (+ params.minutes)
500
Serverfehler
[ERRORS.SERVER_ERROR]

8.4. Authentifizierung

Der Client authentifiziert sich mit [POST /api/auth/login] unter Angabe von Benutzername, Passwort und CAPTCHA-Antwort. Als Antwort sendet der Server im Header [Set-Cookie] seiner Antwort ein Cookie mit einem signierten JWT-Token:

Set-Cookie: rdvmedecins_jwt=eyJhbGciOiJIUzI1NiIs...; Max-Age=7200; Path=/api; HttpOnly; SameSite=Strict

Der Client muss dieses Cookie anschließend im Header [Cookie] bei jeder Anfrage an [/api] mitsenden: So erkennt der Server, wer die Anfrage stellt.

Dieser Server wurde für Web-Clients entworfen, und seine Entwurfsentscheidungen richten sich nach den Risiken, die speziell für Webbrowser gelten:

  • [HttpOnly]: Der [JavaScript]-Code der Seite kann dieses Cookie nicht lesen. Ein in die Seite eingeschleustes bösartiges Skript könnte das Token also 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]: Das Cookie wird nur in Anfragen an die API mitgesendet;
  • [SameSite=Strict]: Der Browser hängt das Cookie nur an Anfragen an, die von einer Seite dieser Website gesendet werden. Eine bösartige Seite auf einer anderen Website kann den Browser nicht dazu bringen, im Namen des Benutzers zu handeln (ein sogenannter CSRF-Angriff);
  • [Max-Age=7200]: Es läuft nach zwei Stunden ab, zugleich mit dem Token.

Eine zweite Schutzmaßnahme gegen CSRF-Angriffe: Der Server weist (415) jede POST-Anfrage zurück, deren Body nicht im JSON-Format vorliegt. Ein kompromittiertes HTML-Formular auf einer anderen Website kann kein JSON senden.

Und eine mobile App? Es gibt keinen Browser: Niemand speichert das Cookie oder sendet es von selbst zurück. Diese Rolle übernimmt die App: Die Bibliothek [OkHttp], der ein „Cookie-Behälter“ (ein [CookieJar]) anvertraut wird, liest den Header [Set-Cookie] der Antworten und schreibt den Header [Cookie] in die Anfragen (Beispiel 23). Die Attribute [HttpOnly] und [SameSite] gelten nur für Browser: Auf die App haben sie keine Wirkung, ebenso wenig wie auf [curl].

8.5. 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 + Zugang
[{ 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 verfügbar?
  • [patient]: der Patient des Termins. Für einen angemeldeten Patienten ist dieser Wert 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, bei einem Patienten, kein bevorstehender Termin)?
  • [appointmentId]: wird 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 erneut prüfen.

8.6. Die API mit curl abfragen

Das Serververzeichnis [curl] enthält die JSON-Bodies der Anfragen dieses Kapitels, eine Datei pro Anfrage. Zum Beispiel [curl/login-admin.json]:

{ "login": "admin", "password": "admin", "captchaId": "-", "captcha": "test" }

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

  • [-i]: zusätzlich die Antwort-Header anzeigen; [-s]: ohne Fortschrittsanzeige;
  • [--json @file]: den Inhalt der Datei per POST senden, mit dem Header [Content-Type: application/json] (curl 7.82 und 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 teils recht langen JSON-Antworten wurden für dieses Dokument formatiert, und die Header [Date], [ETag], [Connection], und [Keep-Alive] wurden entfernt.

8.6.1. Anmeldung

Zuerst das CAPTCHA (das Bild ist zugeschnitten):

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

{"id": "e347ae38-79ff-4dea-8d6e-19610a7d69a7", "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"}

8.6.2. Ärzte, Klienten, Terminkalender

Die Liste der Ärzte aus Sicht von ADMIN (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 es nicht gibt:

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"}

8.6.3. Termine

ADMIN reserviert das Zeitfenster 3 für Patient Nr. 2 (Alice DURAND). Der Body der Anfrage:

{ "day": "2030-01-15", "slotId": 3, "clientId": 2 }
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 einer Anleitung zum Stornieren ([appointmentId]):

$ curl -s -b cookies.txt "http://localhost:8080/api/schedule?doctorId=1&day=2030-01-15"
{
  "doctor": {"id": 1, "version": 0, "title": "Mme", "firstName": "Marie", "lastName": "PELISSIER"},
  "day": "2030-01-15",
  "slots": [
    {"id": 1, "startHour": 8, "startMinute": 0, "endHour": 8, "endMinute": 20, "free": true, "patient": null, "mine": false, "bookable": true, "appointmentId": null},
    {"id": 2, "startHour": 8, "startMinute": 20, "endHour": 8, "endMinute": 40, "free": true, "patient": null, "mine": false, "bookable": true, "appointmentId": null},
    {"id": 3, "startHour": 8, "startMinute": 40, "endHour": 9, "endMinute": 0, "free": false, "patient": {"title": "Mme", "firstName": "Alice", "lastName": "DURAND"}, "mine": false, "bookable": false, "appointmentId": 2},
    {"id": 4, "startHour": 9, "startMinute": 0, "endHour": 9, "endMinute": 20, "free": true, "patient": null, "mine": false, "bookable": true, "appointmentId": null},
    {"id": 5, "startHour": 9, "startMinute": 20, "endHour": 9, "endMinute": 40, "free": true, "patient": null, "mine": false, "bookable": true, "appointmentId": null},
    {"id": 6, "startHour": 9, "startMinute": 40, "endHour": 10, "endMinute": 0, "free": true, "patient": null, "mine": false, "bookable": true, "appointmentId": null},
    {"id": 7, "startHour": 10, "startMinute": 0, "endHour": 10, "endMinute": 20, "free": true, "patient": null, "mine": false, "bookable": true, "appointmentId": null},
    {"id": 8, "startHour": 10, "startMinute": 20, "endHour": 10, "endMinute": 40, "free": true, "patient": null, "mine": false, "bookable": true, "appointmentId": null},
    {"id": 9, "startHour": 10, "startMinute": 40, "endHour": 11, "endMinute": 0, "free": true, "patient": null, "mine": false, "bookable": true, "appointmentId": null},
    {"id": 10, "startHour": 11, "startMinute": 0, "endHour": 11, "endMinute": 20, "free": true, "patient": null, "mine": false, "bookable": true, "appointmentId": null},
    {"id": 11, "startHour": 11, "startMinute": 20, "endHour": 11, "endMinute": 40, "free": true, "patient": null, "mine": false, "bookable": true, "appointmentId": null},
    {"id": 12, "startHour": 11, "startMinute": 40, "endHour": 12, "endMinute": 0, "free": true, "patient": null, "mine": false, "bookable": true, "appointmentId": null}
  ],
  "info": null
}

Noch einmal versuchen: Der Patient hat bereits einen bevorstehenden Termin. Ein Termin in der Vergangenheit wird ebenfalls abgelehnt:

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 mit [-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"}

8.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]: Alices Name, DURAND, wurde nicht gesendet:

$ curl -s -b cookies-martin.txt "http://localhost:8080/api/schedule?doctorId=1&day=2030-01-15"
{
  "doctor": {"id": 1, "version": 0, "title": "Mme", "firstName": "Marie", "lastName": "PELISSIER"},
  "day": "2030-01-15",
  "slots": [
    {"id": 1, "startHour": 8, "startMinute": 0, "endHour": 8, "endMinute": 20, "free": true, "patient": null, "mine": false, "bookable": true, "appointmentId": null},
    {"id": 2, "startHour": 8, "startMinute": 20, "endHour": 8, "endMinute": 40, "free": true, "patient": null, "mine": false, "bookable": true, "appointmentId": null},
    {"id": 3, "startHour": 8, "startMinute": 40, "endHour": 9, "endMinute": 0, "free": false, "patient": null, "mine": false, "bookable": false, "appointmentId": null},
    {"id": 4, "startHour": 9, "startMinute": 0, "endHour": 9, "endMinute": 20, "free": true, "patient": null, "mine": false, "bookable": true, "appointmentId": null},
    {"id": 5, "startHour": 9, "startMinute": 20, "endHour": 9, "endMinute": 40, "free": true, "patient": null, "mine": false, "bookable": true, "appointmentId": null},
    {"id": 6, "startHour": 9, "startMinute": 40, "endHour": 10, "endMinute": 0, "free": true, "patient": null, "mine": false, "bookable": true, "appointmentId": null},
    {"id": 7, "startHour": 10, "startMinute": 0, "endHour": 10, "endMinute": 20, "free": true, "patient": null, "mine": false, "bookable": true, "appointmentId": null},
    {"id": 8, "startHour": 10, "startMinute": 20, "endHour": 10, "endMinute": 40, "free": true, "patient": null, "mine": false, "bookable": true, "appointmentId": null},
    {"id": 9, "startHour": 10, "startMinute": 40, "endHour": 11, "endMinute": 0, "free": true, "patient": null, "mine": false, "bookable": true, "appointmentId": null},
    {"id": 10, "startHour": 11, "startMinute": 0, "endHour": 11, "endMinute": 20, "free": true, "patient": null, "mine": false, "bookable": true, "appointmentId": null},
    {"id": 11, "startHour": 11, "startMinute": 20, "endHour": 11, "endMinute": 40, "free": true, "patient": null, "mine": false, "bookable": true, "appointmentId": null},
    {"id": 12, "startHour": 11, "startMinute": 40, "endHour": 12, "endMinute": 0, "free": true, "patient": null, "mine": false, "bookable": true, "appointmentId": null}
  ],
  "info": null
}

Ein Patient hat keinen Zugriff auf die Klientenliste:

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 reserviert es für sich selbst (der Body enthält kein [clientId]), und zwar nur 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"}
    }
  ]
}

Den Termin eines anderen Patienten kann er 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

{}

8.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"}

8.6.6. Ärzte und Klienten verwalten (ADMIN)

Eine Ergänzung. Fehlt der Benutzername, ist der Standardwert der Name in Kleinbuchstaben; das Passwort ist der Benutzername:

{ "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. Würde man dieselbe Änderung (mit version 1) erneut senden, würde ein Datensatz überschrieben, der inzwischen von jemand anderem geändert wurde: Genau das verhindert das optimistische Sperren:

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

{}

8.6.7. Ein Konto erstellen

Ohne Zugang 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 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=f71fa11a-e899-4d06-a35c-42d203dce17d; Max-Age=900; Path=/api/register; Expires=Mon, 28 Sep 2026 11:04:14 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 Zugang wurde verbraucht: 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"}

8.6.8. Ihr 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:15 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"}

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