Ithy - Ithy

Criando uma REST API Simples com Delphi 12 e Horse

Sim, é perfeitamente possível criar uma REST API simples utilizando o Delphi 12 e o framework Horse. O Horse é um framework web leve e eficiente para Delphi, inspirado em frameworks como o Express.js do Node.js, que facilita a criação de APIs REST de forma rápida e organizada. Este guia detalhado irá te orientar através do processo, desde a configuração do ambiente até a implementação de rotas básicas e testes.

Pré-requisitos

Antes de começar, certifique-se de que você tem o seguinte:

Delphi 12 (ou RAD Studio 12) instalado: Você precisará ter o ambiente de desenvolvimento Delphi instalado em sua máquina.
Framework Horse instalado: O Horse pode ser instalado de algumas formas, sendo a mais recomendada através do Boss, o gerenciador de dependências para Delphi, ou pelo GetIt Package Manager.
Conhecimento básico de Delphi: É útil ter um entendimento básico da linguagem Pascal e do ambiente Delphi.

Instalando o Horse

Existem algumas formas de instalar o framework Horse em seu projeto Delphi. As duas mais comuns são via Boss e via GetIt Package Manager.

Usando o Boss (Recomendado)

O Boss é um gerenciador de dependências que facilita a instalação e atualização de bibliotecas Delphi. Se você ainda não tem o Boss instalado, siga as instruções no repositório oficial do Boss para instalá-lo. Após a instalação, abra o terminal ou prompt de comando e execute o seguinte comando para instalar o Horse:

boss install horse

Este comando irá baixar e instalar o Horse e suas dependências em seu projeto.

Usando o GetIt Package Manager

O GetIt Package Manager é uma ferramenta integrada ao Delphi que permite instalar pacotes e componentes. Para instalar o Horse via GetIt:

Abra o Delphi 12.
Vá em Tools > GetIt Package Manager.
Na janela do GetIt, procure por "Horse".
Selecione o pacote do Horse e clique em "Install".
Siga as instruções na tela para concluir a instalação.

Criando um Novo Projeto Delphi

Agora que você tem o Horse instalado, vamos criar um novo projeto Delphi para a nossa API:

Abra o Delphi 12.
Vá em File > New > Other....
Na janela que se abre, selecione Console Application sob a seção Delphi Projects.
Salve o projeto com um nome apropriado, como HorseApiExample.

Adicionando o Horse ao seu Projeto

Para utilizar o Horse em seu projeto, você precisa adicionar a unit do Horse na cláusula uses do seu arquivo principal (o arquivo .dpr). Abra o arquivo .dpr do seu projeto e adicione Horse à cláusula uses:

program HorseApiExample;

{$APPTYPE CONSOLE}

uses
  System.SysUtils,
  Horse; // Adicione esta linha

Definindo as Rotas da API

Agora, vamos definir as rotas da nossa API. O Horse utiliza funções anônimas (closures) para lidar com as requisições HTTP. Aqui está um exemplo de como criar algumas rotas básicas:

program HorseApiExample;

{$APPTYPE CONSOLE}

uses
  System.SysUtils,
  Horse,
  System.JSON;

procedure ConfigureRoutes;
begin
  // Rota GET para retornar uma mensagem simples
  THorse.Get('/hello',
    procedure(Req: THorseRequest; Res: THorseResponse; Next: TProc)
    begin
      Res.Send('Olá, mundo! Bem-vindo à REST API com Horse!');
    end
  );

  // Rota POST para receber dados e enviar uma resposta
  THorse.Post('/echo',
    procedure(Req: THorseRequest; Res: THorseResponse; Next: TProc)
    var
      RequestBody: string;
    begin
      RequestBody := Req.Body; // Pega o conteúdo do corpo da requisição
      Res.Send('Você enviou: ' + RequestBody);
    end
  );

  // Rota GET com parâmetros dinâmicos
  THorse.Get('/user/:id',
    procedure(Req: THorseRequest; Res: THorseResponse; Next: TProc)
    var
      UserID: string;
    begin
      UserID := Req.Params['id']; // Captura o parâmetro 'id' da URL
      Res.Send(Format('Você consultou o usuário com ID: %s', [UserID]));
    end
  );

  // Rota GET que retorna um JSON
  THorse.Get('/users',
    procedure(Req: THorseRequest; Res: THorseResponse; Next: TProc)
    var
      JSONArray: TJSONArray;
      JSONObject: TJSONObject;
    begin
      JSONArray := TJSONArray.Create;
      try
        // Criando alguns usuários de exemplo
        JSONObject := TJSONObject.Create;
        JSONObject.AddPair('id', '1');
        JSONObject.AddPair('name', 'John Doe');
        JSONObject.AddPair('email', 'john@example.com');
        JSONArray.AddElement(JSONObject);

        JSONObject := TJSONObject.Create;
        JSONObject.AddPair('id', '2');
        JSONObject.AddPair('name', 'Jane Doe');
        JSONObject.AddPair('email', 'jane@example.com');
        JSONArray.AddElement(JSONObject);

        Res.Send<TJSONArray>(JSONArray);
      except
        JSONArray.Free;
        raise;
      end;
    end
  );

  // Rota POST para receber dados JSON
  THorse.Post('/users',
    procedure(Req: THorseRequest; Res: THorseResponse; Next: TProc)
    var
      JSONBody: TJSONObject;
    begin
      JSONBody := Req.Body<TJSONObject>;
      try
        // Aqui você poderia processar os dados recebidos
        // Por exemplo, salvar em um banco de dados

        Res.Status(201);
        Res.Send<TJSONObject>(JSONBody);
      except
        on E: Exception do
        begin
          Res.Status(400);
          Res.Send('Error: ' + E.Message);
        end;
      end;
    end
  );

  // Rota GET com parâmetro na URL que retorna JSON
  THorse.Get('/users/:id',
    procedure(Req: THorseRequest; Res: THorseResponse; Next: TProc)
    var
      Id: string;
      JSONObject: TJSONObject;
    begin
      Id := Req.Params['id'];

      JSONObject := TJSONObject.Create;
      try
        JSONObject.AddPair('id', Id);
        JSONObject.AddPair('name', 'John Doe');
        JSONObject.AddPair('email', 'john@example.com');

        Res.Send<TJSONObject>(JSONObject);
      except
        JSONObject.Free;
        raise;
      end;
    end
  );
end;

begin
  try
    // Inicializando o servidor
    THorse.Use(Logger);

    // Configurando rotas
    ConfigureRoutes;

    // Defina a porta que seu servidor irá responder
    THorse.Listen(9000,
      procedure
      begin
        Writeln('Servidor rodando na porta 9000');
      end); // Servidor ouvindo na porta 9000
  except
    on E: Exception do
      Writeln('Erro ao iniciar o servidor: ', E.Message);
  end;
end.

Explicação do Código

Vamos detalhar o código acima:

THorse.Get('/hello', ...): Define uma rota GET para o caminho /hello. Quando uma requisição GET é feita para este caminho, a função anônima associada é executada, enviando a mensagem "Olá, mundo! Bem-vindo à REST API com Horse!" como resposta.
THorse.Post('/echo', ...): Define uma rota POST para o caminho /echo. Esta rota recebe dados no corpo da requisição e os retorna na resposta.
THorse.Get('/user/:id', ...): Define uma rota GET com um parâmetro dinâmico :id. O valor do parâmetro é acessado através de Req.Params['id'].
THorse.Get('/users', ...): Define uma rota GET para o caminho /users que retorna uma lista de usuários em formato JSON.
THorse.Post('/users', ...): Define uma rota POST para o caminho /users que recebe dados JSON no corpo da requisição e os retorna na resposta.
THorse.Get('/users/:id', ...): Define uma rota GET com um parâmetro dinâmico :id que retorna um usuário específico em formato JSON.
THorse.Use(Logger): Adiciona um middleware de log para registrar as requisições no console.
THorse.Listen(9000, ...): Inicia o servidor na porta 9000 e exibe uma mensagem no console indicando que o servidor está rodando.

Executando a Aplicação

Para executar a aplicação:

Compile o projeto no Delphi.
Execute o aplicativo. Você verá uma mensagem no console indicando que o servidor está rodando na porta 9000.

Testando a API

Você pode usar ferramentas como o Postman, o Curl ou um navegador para testar os endpoints da API:

GET /hello: Acesse http://localhost:9000/hello no seu navegador. Você deverá ver a mensagem "Olá, mundo! Bem-vindo à REST API com Horse!".
POST /echo: Envie uma requisição POST para http://localhost:9000/echo com um corpo de texto (usando, por exemplo, Postman). A resposta deverá ser o mesmo texto que você enviou.
GET /user/123: Acesse http://localhost:9000/user/123 no seu navegador. A resposta deverá ser "Você consultou o usuário com ID: 123".
GET /users: Acesse http://localhost:9000/users no seu navegador. Você deverá ver um JSON com a lista de usuários.
POST /users: Envie uma requisição POST para http://localhost:9000/users com um corpo JSON (usando, por exemplo, Postman). A resposta deverá ser o mesmo JSON que você enviou.
GET /users/1: Acesse http://localhost:9000/users/1 no seu navegador. Você deverá ver um JSON com os dados do usuário com ID 1.

Considerações Adicionais

Estrutura do Projeto: Em projetos maiores, é recomendável organizar o código em múltiplas units para melhor manutenção.
Tratamento de Erros: É importante adicionar tratamento de erros mais robusto para lidar com situações inesperadas.
Banco de Dados: Para persistir os dados, você precisará integrar sua API com um banco de dados.
Autenticação e Autorização: Para proteger sua API, você precisará implementar mecanismos de autenticação e autorização.
Middlewares: O Horse suporta middlewares, que podem ser usados para adicionar funcionalidades como logging, autenticação e tratamento de erros.

Recursos Adicionais

github.com

Repositório do Horse no GitHub

github.com

Documentação Oficial do Horse

github.com

Repositório do Boss no GitHub

Este guia oferece um ponto de partida sólido para criar APIs REST com Delphi 12 e Horse. Com este conhecimento, você pode expandir suas habilidades e construir aplicações web mais complexas e robustas. Se você tiver mais dúvidas, sinta-se à vontade para perguntar!