Skip to content

7. O servidor RdvMedecins, uma caixa-preta

Os exemplos 17 a 20, seguidos do estudo de caso, interagem com um servidor: o servidor JSON da aplicação [RdvMedecins]. Este é o servidor [NestJS] do curso anterior, cujos controllers deixam de gerar páginas HTML e passam a produzir respostas JSON. Suas camadas de negócio e de acesso a dados permanecem inalteradas.

Neste curso, esse servidor é uma caixa-preta: não precisamos saber como ele é escrito. Importa apenas sua API — isto é, a lista de requisições HTTP que ele aceita e as respostas que retorna. Essa é a situação típica de quem desenvolve um cliente: a API é um contrato, e a equipe do servidor pode mudar o que quiser por trás desse contrato. O código-fonte dele é fornecido (pasta [rdvmedecins-nestjs-json]) e amplamente comentado, para o leitor curioso.

Este capítulo explica como instalar o servidor, descreve sua API e o consulta usando o [curl].

7.1. A aplicação RdvMedecins

A aplicação gerencia as consultas de um consultório médico. Ela tem três papéis:

Papel
Quem
O que pode fazer
[ADMIN]
O administrador ([admin])
Agendar e cancelar consultas de todos os pacientes; gerenciar médicos e clientes
[DOCTOR]
Os médicos ([pelissier], [tatou], [dupont])
Agendar e cancelar consultas de todos os pacientes; ver todos os nomes nas agendas
[USER]
Os pacientes ([martin], [durand], [bistrou], [german])
agendar consultas para si mesmos; cancelar suas consultas; gerenciar suas contas. Em uma agenda, não podem ver os nomes dos outros pacientes

As contas de demonstração usam o login como senha. As regras de gestão são verificadas pelo servidor, independentemente do cliente:

  • nenhuma consulta no passado;
  • apenas uma consulta futura por paciente;
  • um horário só pode ser reservado uma vez por dia;
  • dois médicos (ou dois clientes) não podem ter o mesmo nome e sobrenome; um login pertence a uma única conta;
  • um médico com consultas não pode ser excluído;
  • um registro que tenha sido modificado nesse meio tempo por outra pessoa não pode ser sobrescrito (bloqueio otimista);
  • um paciente nunca recebe o nome de outro paciente.

7.2. Instalação

Você precisará do [Node.js] e de um servidor [MySQL] (ou [MariaDB]): sua instalação é descrita no apêndice.

1. O banco de dados. O script [database/dbrdvmedecins2.sql] cria o banco de dados [dbrdvmedecins2], suas tabelas e seus dados de exemplo. Usando o [Laragon], execute-o a partir do [HeidiSQL] (menu Arquivo / Executar um arquivo SQL); na linha de comando:

mysql -u root -p < database/dbrdvmedecins2.sql

O script sempre parte de um banco de dados vazio: você pode executá-lo novamente para restaurar os dados originais.

2. Bibliotecas. Em um console aberto na pasta [rdvmedecins-nestjs-json]:

npm install

3. Configuração. Copie o arquivo [.env.example] para [.env] (no [Windows]: [copy .env.example .env]), depois modifique-o:

# -----------------------------------------------------------------------
# Arquivo de configuração de exemplo.
# Copie este arquivo para [.env] e depois adapte os valores à sua máquina.
# O arquivo [.env] nunca deve ser compartilhado nem versionado (senhas).
# -----------------------------------------------------------------------

# porta de escuta do servidor JSON (o cliente Vue.js o acessa por meio do proxy do Vite)
PORT=8080

# parâmetros de conexão com o banco de dados MySQL [dbrdvmedecins2]
# (script: database/dbrdvmedecins2.sql)
DB_HOST=localhost
DB_PORT=3306
DB_USERNAME=root
DB_PASSWORD=
DB_DATABASE=dbrdvmedecins2
# true: exibe no console as consultas SQL enviadas ao MySQL
DB_LOGGING=false

# -----------------------------------------------------------------------
# autenticação
# -----------------------------------------------------------------------
# chave secreta usada para assinar/verificar tokens JWT - DEVE ser alterada
# em produção (uma string aleatória longa, nunca versionada).
JWT_SECRET=change-me-to-a-long-random-string
# validade de um token JWT, em segundos (7200 s = 2 h). O cookie
# que carrega o token tem a mesma duração.
JWT_EXPIRES_IN_SECONDS=7200
# defina como true em produção (site servido por HTTPS): o cookie de
# autenticação nunca será então enviado por uma conexão não criptografada.
COOKIE_SECURE=false

# -----------------------------------------------------------------------
# proteção contra bots
# -----------------------------------------------------------------------
# login: número de falhas (captcha ou senha errados) permitidas para
# o mesmo login a partir do mesmo endereço IP, antes de bloquear esse par...
LOGIN_MAX_FAILURES=5
# ... por esta duração (um endereço IP também é bloqueado se acumular
# 5 vezes mais falhas, todos os logins somados)
LOGIN_BLOCK_MINUTES=15
# criação de conta de paciente: número máximo de contas criadas por hora
# a partir do mesmo endereço IP. Em uma sala de aula, todos os computadores costumam sair
# pelo mesmo endereço: aumente se necessário.
REGISTRATION_MAX_PER_HOUR=10

# MODO DE TESTE do captcha: se esta variável tiver um valor, esse valor é
# aceito como resposta a QUALQUER captcha. Útil para consultar
# a API com curl (não é possível "ler" a imagem em um console).
# Deixe VAZIA em produção.
CAPTCHA_TEST=

# -----------------------------------------------------------------------
# produção
# -----------------------------------------------------------------------
# pasta do cliente Vue.js compilado, servida por este servidor (padrão: client/)
# CLIENT_DIR=client
# defina como true se o servidor estiver atrás de um proxy (nginx...)
TRUST_PROXY=false
  • linha 8: o servidor escuta na porta 8080;
  • Linhas 12–16: a conexão com o [MySQL]. Com o [Laragon], o usuário [root] não tem senha: os valores padrão servem;
  • linha 25: a chave secreta que assina os tokens de autenticação;
  • linhas 38–45: proteções antibot (bloqueio após várias tentativas de login malsucedidas, número de contas criadas por hora);
  • linha 51: o modo de teste do CAPTCHA. A página de login exige que o usuário digite novamente os caracteres de uma imagem, o que é impossível a partir de um console. Se esta variável tiver um valor, esse valor é aceito como resposta a qualquer CAPTCHA, de modo semelhante às “chaves de teste” que o [Google] oferece para seu [reCAPTCHA]. Para os testes com o [curl] deste capítulo, informe [CAPTCHA_TEST=test]. Deixe-a VAZIA em produção;
  • linhas 57–59: duas configurações para produção (veja o capítulo “Implantação”).

4. Inicialização.

npm run start:dev

O console exibe (trecho):

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

Se o banco de dados estiver inacessível (servidor [MySQL] parado, senha incorreta), o servidor é encerrado imediatamente com uma mensagem de erro de conexão.

7.3. Formato das respostas

Todas as URLs começam por [/api]. Uma requisição bem-sucedida recebe um código de status 2xx e, em seu corpo, os dados solicitados no formato JSON. Uma requisição rejeitada recebe um código de status 4xx ou 5xx e, no corpo, dados no mesmo formato:

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]: o código HTTP, repetido no corpo;
  • [key]: a chave de tradução da mensagem. O servidor nunca retorna texto a ser exibido: ele não conhece mais o idioma do usuário. É o cliente que traduz a chave usando seus dicionários (veja o Exemplo 16);
  • [params] (opcional): os parâmetros da mensagem ([At least {min} characters.], [Try again in {minutes} minute(s).]);
  • [fields] (opcional): para um formulário rejeitado, o erro de cada campo.

Códigos utilizados:

Código
Significado
Exemplos de chaves
400
Requisição inválida
[ERRORS.INVALID_FORM] (+ fields), [ERRORS.INVALID_DATE], [ERRORS.WRONG_CAPTCHA], [ERRORS.CHOOSE_PATIENT], [ERRORS.WRONG_CURRENT_PASSWORD], [ERRORS.BAD_REQUEST]...
401
não autenticado
[ERRORS.AUTH_REQUIRED] (sem token), [ERRORS.SESSION_EXPIRED] (token inválido ou expirado), [LOGIN.ERROR]
403
Acesso negado
[ERRORS.FORBIDDEN] (papel insuficiente), [ERRORS.CAPTCHA_BEFORE_ACCOUNT] (sem passe)
404
Não encontrado
[ERRORS.NOT_FOUND], [ERRORS.DOCTOR_NOT_FOUND], [ERRORS.APPOINTMENT_NOT_FOUND]...
409
Violação de regra de negócio
[ERRORS.PAST_DATE], [ERRORS.SLOT_ALREADY_BOOKED], [ERRORS.LOGIN_TAKEN], [ERRORS.CONCURRENT_UPDATE]...
415
POST que não está em JSON
[ERRORS.JSON_REQUIRED]
429
Tentativas demais
[ERRORS.TOO_MANY_ATTEMPTS], [ERRORS.TOO_MANY_ACCOUNTS] (+ params.minutes)
500
erro do servidor
[ERRORS.SERVER_ERROR]

7.4. Autenticação

O cliente se autentica por meio de [POST /api/auth/login], com um nome de usuário, uma senha e uma resposta ao CAPTCHA. Em troca, o servidor coloca no navegador um cookie que contém um token JWT assinado:

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

Seus atributos são importantes para a segurança:

  • [HttpOnly]: o código [JavaScript] da página não consegue ler esse cookie. Um script malicioso injetado na página seria, portanto, incapaz de roubar o token. Consequência para o cliente: ele não consegue determinar por conta própria se está logado. Ele pergunta ao servidor ([GET /api/auth/me]);
  • [Path=/api]: o navegador só o inclui nas requisições à API;
  • [SameSite=Strict]: o navegador só inclui esse token nas requisições enviadas A PARTIR de uma página deste site. Uma página maliciosa em outro site não consegue fazer o navegador agir em nome do usuário (um chamado ataque CSRF);
  • [Max-Age=7200]: ele expira após duas horas, ao mesmo tempo que o token.

O navegador envia então automaticamente esse cookie a cada requisição a [/api]. O cliente [Vue.js] não tem, portanto, nada a fazer para se autenticar, desde que suas páginas e a API compartilhem a mesma origem (mesmo protocolo, mesma máquina, mesma porta). Esse é o papel do proxy do [Vite] durante o desenvolvimento (veja o Exemplo 17) e do próprio servidor em produção (veja o capítulo “Implantação”).

Uma segunda salvaguarda contra ataques CSRF: o servidor rejeita (415) qualquer requisição POST cujo corpo não esteja em JSON. Um formulário HTML comprometido em outro site não consegue enviar JSON.

7.5. A API

Método
Endereço
Papéis
Corpo enviado/resposta
GET
[/api/captcha]
público
Resposta: [{ id, svg }]
POST
[/api/auth/login]
público
[{ login, password, captchaId, captcha }]; resposta: [{ login, name, role }] + cookie
POST
[/api/auth/logout]
público
[{}] ; exclui o cookie
GET
[/api/auth/me]
logado
resposta: [{ login, name, role }]
GET
[/api/schedule?doctorId=&day=]
todos
Resposta: a agenda (sem doctorId: para um DOCTOR, a sua própria)
POST
[/api/appointments]
todos
[{ day, slotId, clientId }] (clientId ignorado para um USER); 201
DELETE
[/api/appointments/:id]
todos
Um USER só cancela as suas próprias
GET
[/api/doctors]
todos
a lista (com login para o ADMIN)
GET
[/api/clients]
ADMIN, DOCTOR
a lista (com login para o ADMIN)
GET
[/api/doctors/:id], [/api/clients/:id]
ADMIN
uma ficha cadastral
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
Resposta: [{}]
POST
[/api/register/access]
público
[{ captchaId, captcha }]; emite um token (cookie)
GET
[/api/register/access]
público
resposta: [{ valid }]
POST
[/api/register]
público + passe
[{ title, firstName, lastName, login, password, confirmation }]; 201
GET
[/api/my-area]
USER
resposta: [{ patient, appointments }]
GET
[/api/my-account]
USER
Resposta: [{ title, firstName, lastName, login, version }]
PUT
[/api/my-account]
USER
[{ title, firstName, lastName, login, password?, confirmation?, currentPassword, version }]
DELETE
[/api/my-account]
USER
[{ currentPassword }]; exclui a conta e suas consultas

Uma entrada da agenda ([GET /api/schedule]) descreve um horário E o que o usuário logado está autorizado a fazer com ele:

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]: o horário está disponível nesse dia?
  • [patient]: o paciente da consulta. Para um paciente logado, é igual a [null], exceto para a PRÓPRIA consulta dele: os nomes dos outros pacientes nunca são enviados;
  • [mine]: esta é a consulta do paciente logado;
  • [bookable]: o usuário pode reservar este horário (disponível, não no passado e, para um paciente, sem consultas futuras)?
  • [appointmentId]: preenchido se o usuário puder cancelar esta consulta.

O servidor DECIDE; o cliente exibe. E mesmo que um cliente trapaceasse (exibindo um botão “Reservar” quando não deveria), o servidor verificaria tudo novamente no momento da reserva.

7.6. Consultando a API com curl

A pasta [curl] do servidor contém os corpos de requisição JSON deste capítulo, um arquivo por requisição. Por exemplo, [curl/login-admin.json]:

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

Os comandos são digitados em um console aberto no diretório [rdvmedecins-nestjs-json]. Algumas opções do [curl]:

  • [-i]: exibir também os cabeçalhos da resposta; [-s]: sem barra de progresso;
  • [--json @file]: enviar o conteúdo do arquivo em POST, com o cabeçalho [Content-Type: application/json] (curl 7.82 e posteriores; com uma versão mais antiga, use [-H "Content-Type: application/json" -d @file]);
  • [-X PUT], [-X DELETE]: o método HTTP;
  • [-c cookies.txt]: salvar os cookies recebidos neste arquivo; [-b cookies.txt]: enviá-los de volta. É assim que o [curl] “permanece logado” de um comando para o seguinte, exatamente como faria um navegador.

No [PowerShell], é preciso digitar [curl.exe], e não [curl] (que designa outro comando). As respostas um tanto longas em JSON foram formatadas para este documento, e os cabeçalhos [Date], [ETag], [Connection], e [Keep-Alive] foram removidos.

7.6.1. Login

Primeiro, o CAPTCHA (a imagem foi recortada):

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

{"id": "abf00f0c-60c0-4fde-9782-9906815e26a1", "svg": "<svg xmlns=\"http://www.w3.org/2000/svg\" width=\"150..."}

Sem token, uma URL protegida retorna uma resposta 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"}

Um CAPTCHA incorreto, seguido de uma senha incorreta:

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

Um login bem-sucedido define o cookie, que o [curl] armazena em [cookies.txt]:

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

Com esse cookie, o servidor sabe quem somos:

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

Um token falsificado (ou expirado) resulta em uma sessão expirada, e o servidor instrui o navegador a apagar o cookie:

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. Médicos, clientes, calendário

A lista de médicos, vista pelo ADMIN (com os 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"}
]

Agenda do Dr. PELISSIER para 15 de janeiro de 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
}

Uma data que não existe:

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

O ADMIN reserva o horário 3 para o paciente nº 2 (Alice DURAND). O corpo da requisição:

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

O calendário agora exibe essa consulta, junto com o nome do paciente e as instruções para cancelá-la ([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
}

Tente novamente: o paciente já tem uma consulta futura. Uma consulta no passado também é rejeitada:

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

Um formulário HTML padrão (simulado aqui por [-d], que envia [application/x-www-form-urlencoded]) é rejeitado:

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. A perspectiva de um paciente

Você faz logout e depois login como [martin]:

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

A mesma agenda, vista por um paciente: o horário 3 está ocupado (["free": false]), mas ["patient"] equivale a [null]: o nome de Alice, DURAND, não foi enviado:

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

Um paciente não tem acesso à lista de clientes:

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

Ele faz uma reserva para si mesmo (o corpo não contém [clientId]), uma vez, não duas:

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

Sua área:

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

Ele não pode cancelar a consulta de outro paciente. O servidor responde “não encontrado”, exatamente como faria para uma consulta que não existe: não revela nada sobre as consultas dos outros pacientes:

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

A sua própria, sim:

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. A perspectiva de um médico

Sem [doctorId], um médico logado recebe a SUA PRÓPRIA agenda, com todos os nomes:

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

Ele não gerencia médicos:

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. Gerenciamento de médicos e clientes (ADMIN)

Uma inclusão. Se o nome de usuário estiver ausente, o padrão é o nome em minúsculas; a senha é o nome de usuário:

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

Corpo inválido: a resposta lista o erro de cada campo:

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

Um homônimo: os dois campos afetados são sinalizados:

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

Uma alteração. A [version] é a lida na ficha de dados (aqui, 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"}

O registro agora está na versão 2. Reenviar a mesma alteração (com a versão 1) sobrescreveria um registro que foi modificado por outra pessoa nesse meio-tempo: o bloqueio otimista impede isso:

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

Um médico com consultas não pode ser excluído; os demais podem:

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. Criação de uma conta

Sem o passe, é impossível:

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

Primeiro, você resolve um CAPTCHA; o servidor emite um token, válido por 15 minutos, em um 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=06be5557-401a-4bd4-ada2-277ca48fc74d; Max-Age=900; Path=/api/register; Expires=Mon, 28 Sep 2026 11:04:12 GMT; HttpOnly; SameSite=Strict
Content-Type: application/json; charset=utf-8
Content-Length: 2

{}
$ curl -s -b cookies-registration.txt http://localhost:8080/api/register/access
{"valid": true}

A confirmação da senha deve ser idêntica:

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

O passe já foi usado: ele não pode ser usado para criar uma segunda conta:

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. Gerenciar sua conta

A nova paciente faz login e lê sua ficha:

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

Fazer uma alteração exige a senha atual. O servidor emite um novo token, que contém o novo nome:

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

Excluir a conta também apaga o 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. Alguns erros

Uma rota desconhecida, um corpo que não é um JSON válido:

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

Agora sabemos tudo o que precisamos saber sobre o servidor para escrever o nosso cliente.