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]. Trata-se do servidor [NestJS] da lição anterior, cujos controllers não geram mais páginas HTML, mas produzem 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 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 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] | Médicos ([pelissier], [tatou], [dupont]) | Agendar e cancelar consultas de todos os pacientes; ver todos os nomes nas agendas |
[USER] | Pacientes ([martin], [durand], [bistrou], [german]) | Marcar consultas para si mesmos; cancelar suas consultas; gerenciar suas contas. Em uma agenda, não veem 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);
- a um paciente nunca é atribuído 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 a partir do [HeidiSQL] (menu Arquivo / Executar 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 iniciais.
2. Bibliotecas. Em uma janela de console aberta na pasta [rdvmedecins-nestjs-json]:
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 React o acessa pelo 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 commitada).
JWT_SECRET=change-me-to-a-long-random-string
# validade de um token JWT, em segundos (7200 s = 2 h). O cookie
# que transporta 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 este 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
# 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 React 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: modo de teste do CAPTCHA. A página de login pede que você digite os caracteres de uma imagem, o que é impossível a partir de um console. Se essa variável tiver um valor, ele é aceito como resposta a qualquer CAPTCHA, assim como as “chaves de teste” que o [Google] fornece para seu [reCAPTCHA]. Para os testes com o [curl] neste 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.
O console exibe (trecho):
| [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, em seu corpo, os dados solicitados em formato JSON. Uma requisição rejeitada recebe um código 4xx ou 5xx e, no corpo, um erro que SEMPRE tem o mesmo formato:
| {
"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 para exibição: 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): 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 em excesso | [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 usando [POST /api/auth/login], com 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 pode ler esse cookie. Um script malicioso que eventualmente tenha sido 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á autenticado. 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 pode fazer o navegador agir em nome do usuário (o 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 para [/api]. O cliente [React] 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). Esse é o papel do proxy do servidor de desenvolvimento, o [Vite] (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] | autenticado | 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 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 autenticado está autorizado a fazer com ele:
| { "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 autenticado, é igual a [null], exceto para a SUA PRÓPRIA consulta: os nomes dos outros pacientes nunca são enviados;
- [mine]: é a consulta do paciente autenticado;
- [bookable]: o usuário pode reservar este horário (disponível, não 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 “Agendar” quando não deveria), o servidor verificaria tudo novamente no momento da reserva.
A pasta [curl] do servidor contém os corpos JSON das requisições 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]: exibe também os cabeçalhos da resposta; [-s]: sem barra de progresso;
- [--json @file]: envia 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]: salva os cookies recebidos neste arquivo; [-b cookies.txt]: envia-os de volta. É assim que o [curl] “permanece autenticado” de um comando para o seguinte, exatamente como faria um navegador.
No [PowerShell], você deve digitar [curl.exe] e não [curl] (que ali 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 está cortada):
| $ curl -i http://localhost:8080/api/captcha
HTTP/1.1 200 OK
Cache-Control: no-store
Content-Type: application/json; charset=utf-8
Content-Length: 11528
{"id": "be956764-1c67-4d23-a744-d0c2cebbb791", "svg": "<svg xmlns=\"http://www.w3.org/2000/svg\" width=\"150..."}
|
Sem um token, uma URL protegida retorna uma resposta 401:
| $ 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:
| $ 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"}}
|
| $ 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]:
| $ 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:
| $ 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 forjado (ou expirado) resulta em uma sessão expirada, e o servidor instrui o navegador a excluir o cookie:
| $ 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:
| $ 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 }
|
| $ 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 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:
| $ 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"}
|
| $ 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:
| $ 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]:
| $ 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:
| $ 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 }
|
| $ 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}
|
| $ 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: ele não revela nada sobre as consultas de outros pacientes:
| $ 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:
| $ 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 autenticado 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:
| $ 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 estiver ausente, o padrão é o nome em minúsculas; a senha é o login:
| { "title": "Mme", "firstName": "Claire", "lastName": "LEROY" }
|
| $ 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:
| $ 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. A [version] é a lida no registro (aqui, 1):
| { "title": "Mme", "firstName": "Claire", "lastName": "LEROY-MARTIN", "version": 1 }
|
| $ 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:
| $ 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 outros podem:
| $ 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"}
|
| $ 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:
| $ 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:
| $ curl -i -c cookies-registration.txt --json @curl/captcha-test.json http://localhost:8080/api/register/access
HTTP/1.1 200 OK
Set-Cookie: rdvmedecins_registration=fd231085-46dc-4a97-bc61-ea84494ee3c2; Max-Age=900; Path=/api/register; Expires=Mon, 28 Sep 2026 11:04:12 GMT; HttpOnly; SameSite=Strict
Content-Type: application/json; charset=utf-8
Content-Length: 2
{}
|
| $ curl -s -b cookies-registration.txt http://localhost:8080/api/register/access
{"valid": true}
|
A confirmação da senha deve ser idêntica:
| $ 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" }
|
| $ 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:
| $ 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ê seu prontuário:
| $ curl -s -b cookies-jbernard.txt http://localhost:8080/api/my-account
{"title": "Mme", "firstName": "Julie", "lastName": "BERNARD", "login": "jbernard", "version": 1}
|
Qualquer 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 }
|
| $ 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:
| $ 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
{}
|
| $ 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:
| $ 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"}
|
| $ 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 nosso cliente.