Skip to content

7. O servidor RdvMedecins, uma caixa-preta

Os exemplos 22 a 25, seguidos do estudo de caso, interagem com um servidor: o servidor JSON da aplicação [RdvMedecins]. Este é o servidor [NestJS] da lição 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 a sua API, isto é, a lista de requisições HTTP que ele aceita e as respostas que retorna. Esta é a situação típica de um desenvolvedor de cliente: a API é um contrato, e a equipe do servidor pode mudar o que quiser por trás desse contrato. Seu código-fonte é fornecido (pasta [rdvmedecins-nestjs-json]) e amplamente comentado, para o leitor curioso.

Este capítulo explica como instalar o servidor, descreve sua API e a consulta com [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])
Marcar consultas para si mesmos; cancelar suas consultas; gerenciar suas contas. Na agenda, não veem os nomes dos outros pacientes

As contas de demonstração usam o login como senha. As regras de gerenciamento 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]): a instalação deles é 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. Com o [Laragon], execute-o no [HeidiSQL] (menu Arquivo / Executar arquivo SQL); na linha de comando:

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

O script sempre começa com um banco de dados vazio: você pode executá-lo novamente para restaurar os dados iniciais.

2. Bibliotecas. Em uma janela de console aberta na pasta [rdvmedecins-nestjs-json]:

npm install

3. Configuração. Copie o arquivo [.env.example] para [.env] (no [Windows]: [copy .env.example .env]) e 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 commitado (senhas).
# -----------------------------------------------------------------------

# porta de escuta do servidor JSON (o cliente Angular o alcança pelo proxy do ng serve)
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 commitada).
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 incorretos) permitidas para
# o mesmo login a partir do mesmo endereço IP, antes de esse par ser bloqueado...
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 cliente: 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

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

# -----------------------------------------------------------------------
# produção
# -----------------------------------------------------------------------
# pasta do cliente Angular compilado, servido 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 forma semelhante às “chaves de teste” que o [Google] fornece para o seu [reCAPTCHA]. Para os testes com o [curl] neste capítulo, digite [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. Execuçã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 com [/api]. Uma requisição bem-sucedida recebe um código de status 2xx e, no 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 21);
  • [params] (opcional): 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 com [POST /api/auth/login], enviando um nome de usuário, uma senha e a 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 pode determinar por conta própria se está conectado. 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 ataque conhecido como CSRF);
  • [Max-Age=7200]: ele expira após duas horas, ao mesmo tempo que o token.

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

Uma segunda proteção 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]
conectado
resposta: [{ login, name, role }]
GET
[/api/schedule?doctorId=&day=]
todos
Resposta: a agenda (sem doctorId: para um DOCTOR, a própria)
POST
[/api/appointments]
todos
[{ day, slotId, clientId }] (clientId ignorado para um USER); 201
DELETE
[/api/appointments/:id]
todos
Um USER cancela apenas as suas próprias
GET
[/api/doctors]
todos
a lista (com login para ADMIN)
GET
[/api/clients]
ADMIN, DOCTOR
a lista (com login para ADMIN)
GET
[/api/doctors/:id], [/api/clients/:id]
ADMIN
um registro
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 conectado 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 conectado, vale [null], exceto nas consultas DELE MESMO: os nomes dos outros pacientes nunca são enviados;
  • [mine]: esta é a consulta do paciente conectado;
  • [bookable]: o usuário pode reservar este horário (disponível, não está 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 “Book” quando não deveria), o servidor verificaria tudo novamente no momento da reserva.

7.6. Consultar a API com curl

A pasta [curl] do servidor contém os corpos de requisição JSON deste capítulo, com 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]: exibe também os cabeçalhos da resposta; [-s]: sem barra de progresso;
  • [--json @file]: envia o conteúdo do arquivo em um 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]: salva os cookies recebidos neste arquivo; [-b cookies.txt]: os envia de volta. É assim que o [curl] “continua conectado” de um comando para o seguinte, exatamente como faria um navegador.

No [PowerShell], é preciso digitar [curl.exe] e não [curl] (que lá se refere a outro comando). As respostas JSON, um tanto longas, 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: 11304

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

Sem um 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 excluir 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, agenda

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

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

A agenda passa a exibir 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ê sai da sessão e depois entra 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"}

A área dele:

$ 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 com “não encontrado”, exatamente como faria para uma consulta que não existe: ele 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 dele mesmo, 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 conectado 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 login for omitido, o padrão é o nome em minúsculas; a senha é o 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"}

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 modificação. O [version] é o lido do registro (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 nesse meio-tempo por outra pessoa: 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 um 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=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}

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 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ê o registro de sua conta:

$ 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 exclui 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.