8. 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]. É o servidor [NestJS] dos cursos [React], [Vue.js] e [Angular]: o servidor do curso [NestJS], cujos controllers deixaram de gerar páginas HTML e passaram a produzir respostas JSON. Os leitores destas aulas já conhecem este capítulo, reproduzido aqui quase sem alterações; basta se concentrarem na seção sobre autenticação, que explica o que muda para uma aplicação mobile.
Neste curso, este servidor é uma caixa-preta: você não precisa saber como ele é escrito. O que importa é apenas a sua API, ou seja, a lista de requisições HTTP que ele aceita e as respostas que devolve. Esta é a situação típica de um desenvolvedor de clientes: a API é um contrato, e a equipe do servidor pode mudar o que quiser por trás desse contrato. O 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 [curl].
8.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);
- um paciente nunca recebe o nome de outro paciente.
8.2. Instalação
Você precisa do [Node.js] e de um servidor [MySQL] (ou [MariaDB]): a instalação deles é descrita no apêndice.
- 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 um 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.
- Bibliotecas. Em uma janela de console aberta na pasta [rdvmedecins-nestjs-json]:
- 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 versionado (senhas).
# -----------------------------------------------------------------------
# porta de escuta do servidor JSON
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 que esse par seja 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 web 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: medidas 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 exige que você digite 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, como as “chaves de teste” que o [Google] oferece para o seu [reCAPTCHA]. Para os testes com o [curl] neste capítulo, informe [CAPTCHA_TEST=test]. Os testes automatizados que geraram as capturas de tela deste curso também usam esse valor. Deixe-a VAZIA em produção;
- linhas 57–59: duas configurações para produção (veja o capítulo “Implantação”).
- 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.
8.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 em formato JSON. Uma requisição rejeitada recebe um código 4xx ou 5xx e, no corpo, um objeto 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 devolve 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 usados:
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] |
8.4. Autenticação
O cliente se autentica com [POST /api/auth/login], informando um nome de usuário, uma senha e a resposta ao CAPTCHA. Em retorno, o servidor envia, no cabeçalho [Set-Cookie] de sua resposta, um cookie contendo um token JWT assinado:
| Set-Cookie: rdvmedecins_jwt=eyJhbGciOiJIUzI1NiIs...; Max-Age=7200; Path=/api; HttpOnly; SameSite=Strict
|
O cliente deve então incluir esse cookie, no cabeçalho [Cookie], em toda requisição a [/api]: é assim que o servidor sabe quem está fazendo a requisição.
Este servidor foi concebido para clientes web, e suas escolhas de projeto são guiadas pelos riscos específicos dos navegadores:
- [HttpOnly]: o código da página ([JavaScript]) 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 cookie só é incluído nas requisições à API;
- [SameSite=Strict]: o navegador anexa o cookie apenas às 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 (um ataque conhecido como CSRF);
- [Max-Age=7200]: ele expira após duas horas, ao mesmo tempo que o token.
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.
E uma aplicação mobile? Não há navegador: ninguém armazena o cookie nem o reenvia por conta própria. A aplicação assumirá esse papel, lendo o cabeçalho [Set-Cookie] nas respostas e escrevendo o cabeçalho [Cookie] nas requisições (exemplo 23). Os atributos [HttpOnly] e [SameSite] só se aplicam aos navegadores: não têm efeito sobre a aplicação, assim como não têm sobre o [curl]. A mesma aplicação [Flutter], quando compilada para a web, funcionará, porém, como os navegadores: o cookie é gerenciado pelo navegador, desde que a aplicação e a API compartilhem a mesma origem (veja o exemplo 22 e o capítulo “Implantação”).
8.5. A API
Método | Endereço | Papéis | Corpo enviado/resposta |
GET | [/api/captcha] | pública | Resposta: [{ id, svg }] |
POST | [/api/auth/login] | pública | [{ login, password, captchaId, captcha }]; resposta: [{ login, name, role }] + cookie |
POST | [/api/auth/logout] | pública | [{}] ; 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 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ública | [{ captchaId, captcha }]; emite um token (cookie) |
GET | [/api/register/access] | pública | resposta: [{ valid }] |
POST | [/api/register] | pública + 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:
| { "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 SUA PRÓPRIA consulta: 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 está no passado e, para um paciente, sem consultas futuras)?
- [appointmentId]: preenchido se o usuário pode 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.
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 na pasta [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]: os reenvia. É assim que o [curl] “permanece logado” de um comando para o outro, exatamente como faria um navegador.
No [PowerShell], é preciso 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.
8.6.1. Login
Primeiro, o CAPTCHA (a imagem foi recortada):
| $ 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: 11428
{"id": "968678a8-25f0-4892-9fc4-bd93533dab33", "svg": "<svg xmlns=\"http://www.w3.org/2000/svg\" width=\"150..."}
|
Sem token, uma URL protegida devolve 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"}
|
8.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"}
|
8.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 comum (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"}
|
8.6.4. O ponto de vista de um paciente
Você faz logout e depois faz 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"] é igual 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"}
|
A 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:
| $ 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:
| $ curl -i -b cookies-martin.txt -X DELETE http://localhost:8080/api/appointments/3
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 2
{}
|
8.6.5. O ponto de vista 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:
| $ curl -i -b cookies-pelissier.txt --json @curl/doctor-add.json http://localhost:8080/api/doctors
HTTP/1.1 403 Forbidden
Content-Type: application/json; charset=utf-8
Content-Length: 43
{"statusCode": 403, "key": "ERRORS.FORBIDDEN"}
|
8.6.6. Gerenciando médicos e clientes (ADMIN)
Uma inclusão. Se o login for omitido, o padrão é o sobrenome 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 que foi lida do 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 demais 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
{}
|
8.6.7. Criando uma conta
Sem 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=60f5fa35-f939-4c87-b5a2-7c2f38054cc3; 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: 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"}
|
8.6.8. Gerenciando 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 }
|
| $ 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"}
|
8.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.