Repository navigation
hipermidia
Home > Plugins > HAL, JSON:API e HTML 🚧
Important
Em desenvolvimento (2.0). Ainda não está numa versão lançada e pode mudar.
Vale para a 2.0 · Delphi XE em diante e Lazarus/FPC 3.2 em diante · Nível: intermediário
Em uma frase: o TRALHypermediaPlugin faz a mesma rota responder JSON puro, HAL
(application/hal+json), JSON:API (application/vnd.api+json) ou uma página HTML,
conforme o cabeçalho Accept, com os links de cada recurso; os handlers continuam
respondendo o JSON de sempre.
Você vai precisar: o pacote RALModuleHypermediaPackage (requer o
RALModuleWebPackage, pelos templates).
uses RALHypermedia;
FHiper := TRALHypermediaPlugin.Create(Self);
vRecurso := FHiper.Resources.Add;
vRecurso.Path := 'clientes/:id'; // as rotas que ele cobre (:nome pega um trecho)
vRecurso.ResourceType := 'clientes';
vRecurso.Links.Add('pedidos=/clientes/{id}/pedidos');
vRecurso.Title := 'Cliente';
vRecurso := FHiper.Resources.Add;
vRecurso.Path := 'clientes';
vRecurso.ResourceType := 'clientes';
vRecurso.ItemHref := '/clientes/{id}'; // o link de cada item da lista
FHiper.Server := FServidor;Num link, um nome entre chaves vem do caminho (:id de Path) ou de um campo do
objeto. IdField (padrão id) diz qual campo é o id.
Para GET /clientes/7, cujo handler responde {"id":7,"nome":"Ana"}:
Accept |
resposta |
|---|---|
(nenhum) ou application/json
|
{"id":7,"nome":"Ana"}, como o handler respondeu |
application/hal+json |
{"id":7,"nome":"Ana","_links":{"self":{"href":"/clientes/7"},"pedidos":{"href":"/clientes/7/pedidos"}}} |
application/vnd.api+json |
{"links":{...},"data":{"type":"clientes","id":"7","attributes":{"nome":"Ana"}}} |
text/html |
uma página com os campos e os links; com Template e Templates, o seu template Mustache
|
- Uma lista vira
_embeddedno HAL edatacom um item por objeto no JSON:API, cada um com o seu link (ItemHref). - Só respostas 2xx em JSON são reescritas: um erro sai como o handler respondeu.
- A resposta leva
Vary: Accept, para os caches guardarem uma cópia por formato. -
Formatsescolhe quais dos três o servidor oferece.
| sintoma | causa | o que fazer |
|---|---|---|
| a resposta sai em JSON puro | o Path do recurso não bate com a rota, ou o Accept não pede um dos formatos |
confira o Path (sem barra inicial, :nome para os trechos variáveis) |
| a página HTML não usa o template |
Templates sem um motor ligado, ou o template falhou |
ligue um TRALMustacheEngine e confira o nome |
Começar
Servidor
- Rotas e parâmetros
- Rotas avançadas: tipos, grupos, versões 🚧
- Ler o pedido e responder
- Objetos no corpo 🚧
- Resposta em fluxo 🚧
- Plugins 🚧
- Serviços (contêiner de dependências) 🚧
- Barramento de eventos 🚧
- Tarefas em segundo plano 🚧
- Recursos com estado 🚧
- Autenticação
- Banco de dados (DBWare)
- Servir site e arquivos
- JSON-RPC 2.0 🚧
- Servidor MCP (IA) 🚧
-
Protocol Buffers 🚧
- gRPC 🚧
- WebSocket 🚧
- Hubs (WebSocket) 🚧
- Swagger e Postman
- Servidor SOAP 🚧
- WS-Security 🚧
- HTTPS
- Criptografia ponto a ponto
- Segurança para produção
- Colocar no ar
- Desempenho
- Testes em memória 🚧
MQTT 🚧
- O que é e quando usar 🚧
- Cliente MQTT 🚧
- Broker MQTT 🚧
- MQTT-SN 🚧
- Ponte REST 🚧
- Segurança 🚧
- Rede ruim 🚧
E-mail 🚧
- Mensagens 🚧
- Enviar 🚧
- Receber 🚧
- Ler a caixa postal 🚧
- Verificar o que chega 🚧
- Servir caixas postais 🚧
- S/MIME 🚧
- OpenPGP 🚧
Chatbot 🚧
- O robô e os canais 🚧
- Telegram 🚧
- Gateways REST (WhatsApp não oficial) 🚧
- Discord 🚧
- Slack 🚧
- Microsoft Teams 🚧
- Conversa em etapas 🚧
Cliente
Motores
- Qual motor escolher?
- Compatibilidade
- Recursos
- QUIC
- Motor NgHttp2 (HTTP/2) 🚧
- Motor XSocket 🚧
- Motor AdvancedHTTP (experimental) 🚧
Avançado
Ajuda
- Problemas comuns
- Atualizar o Indy
- Várias versões do Delphi
- Vídeos e guias
- Módulos de terceiros
- Licenças
- Contribuir
- Roadmap e changelog
🚧 = em desenvolvimento, pode mudar