Skip to content
mobius1qwe edited this page Nov 16, 2026 · 1 revision

Home > Plugins > HAL, JSON:API e HTML 🚧

Hipermídia: HAL, JSON:API e HTML pelo Accept

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

Montando

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.

O que sai

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 _embedded no HAL e data com 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.
  • Formats escolhe quais dos três o servidor oferece.

Erros comuns

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

Veja também

Começar

Servidor

MQTT 🚧

E-mail 🚧

Chatbot 🚧

Cliente

Motores

Avançado

Ajuda

🚧 = em desenvolvimento, pode mudar

Clone this wiki locally