rotas

Home > Rotas e parâmetros

Rotas e parâmetros

Vale para a 1.1 em diante · Delphi e Lazarus · Nível: iniciante

Em uma frase: a rota diz qual endereço o servidor atende, com quais métodos, e
qual código responde.

Você vai precisar: ter feito o Primeiro servidor.

Criar uma rota

Servidor.CreateRoute('clientes', ListarClientes, 'lista os clientes');

• 'clientes' → atende /clientes. Subníveis à vontade: 'api/v1/clientes'.
• ListarClientes → o procedimento que responde. Pode ser um método de um
  formulário ou um procedimento solto (como no primeiro exemplo).
• o terceiro parâmetro é a descrição, que aparece no Swagger.

No Lazarus sem {$MODE DELPHI}, ponha @ antes do nome: @ListarClientes. O
código do próprio RAL escreve assim: {$IFDEF FPC}@{$ENDIF}ListarClientes.

O procedimento sempre tem esta forma:

procedure TForm1.ListarClientes(ARequest: TRALRequest; AResponse: TRALResponse);
begin
  AResponse.Answer(HTTP_OK, '[{"id":1,"nome":"Ana"}]', rctAPPLICATIONJSON);
end;

Escolher os métodos

Por padrão uma rota aceita todos os métodos. Para limitar:

Servidor.CreateRoute('clientes', ListarClientes).AllowedMethods := [amGET, amPOST];

Atalho, desde a 1.2 🚧, que permite encadear:

Servidor.CreateRoute('clientes', ListarClientes).Allow([amGET, amPOST]).SkipAuth([amGET]);

Propriedade	O que faz
AllowedMethods / Allow([...])	métodos aceitos; os outros respondem 405 (antes da 1.2 🚧, 404)
SkipAuthMethods / SkipAuth([...])	métodos que não pedem login, mesmo com autenticação ligada (ex.: GET público, POST com senha)

Métodos: amGET, amPOST, amPUT, amPATCH, amDELETE, amHEAD, amOPTIONS,
amTRACE, amALL (todos). Precisa de RALTypes no uses.

[!NOTE]
OPTIONS é respondido pelo próprio RAL para o CORS: você não
precisa tratar.

Parâmetro no caminho: /clientes/7

Escreva o nome do parâmetro com : na frente:

Servidor.CreateRoute('clientes/:id', BuscarCliente);

procedure TForm1.BuscarCliente(ARequest: TRALRequest; AResponse: TRALResponse);
var
  vId: Integer;
begin
  vId := ARequest.ParamByName('id').AsInteger;   // 7
  AResponse.Answer(HTTP_OK, Format('{"id":%d}', [vId]), rctAPPLICATIONJSON);
end;

Parâmetro na URL: /clientes?cidade=Recife

Não precisa declarar nada: ARequest.ParamByName('cidade').AsString. O mesmo
ParamByName lê campos de formulário, cabeçalhos e cookies. Detalhes em
Ler o pedido e responder.

[!WARNING]
ParamByName devolve nil quando o parâmetro não veio. Antes de ler, teste:
if ARequest.ParamByName('cidade') <> nil then ...

Um código por método na mesma rota

Desde a 1.1, duas rotas podem ter o mesmo endereço com métodos diferentes:

Servidor.CreateRoute('clientes', ListarClientes).AllowedMethods := [amGET];
Servidor.CreateRoute('clientes', CriarCliente).AllowedMethods := [amPOST];

Documentar os parâmetros

InputParams (o que a rota recebe) e OutputParams (o que ela devolve, 1.2 🚧)
listam os parâmetros na ordem certa. O Swagger mostra os de entrada. Na
rota, ARequest.Route (1.2 🚧) dá acesso à rota que está respondendo.

Rotas pelo Object Inspector

Com o servidor no formulário: dois cliques em Routes, Add, preencha Route
(clientes/:id), AllowedMethods, e dê dois cliques no evento OnReply para
escrever o código.

Erros comuns

O que acontece	Causa	O que fazer
404	o endereço não bate com nenhuma rota	confira a grafia; :id precisa de um valor (/clientes/7)
405	o método não está em AllowedMethods	acrescente o método
401 numa rota que devia ser pública	autenticação ligada no servidor	SkipAuth([amGET]) na rota
Access violation ao ler um parâmetro	ParamByName devolveu nil	teste antes de usar

Veja também

• Ler o pedido e responder
• Autenticação
• Criando um módulo: um grupo de rotas reaproveitável