Curso NestJS for Azure: #2 Controllers

No desenvolvimento de APIs modernas, o conceito de REST (Representational State Transfer) e a arquitetura RESTful se tornaram padrões amplamente adotados. Com a popularidade de frameworks como o NestJS, que facilitam a construção de APIs robustas e escaláveis, é essencial entender esses conceitos fundamentais. Neste artigo, vamos explorar o que são REST e RESTful, e como a camada de Controller no NestJS desempenha um papel crucial na construção de APIs RESTful.

O Que é REST?

REST, ou Representational State Transfer, é um estilo arquitetônico para sistemas distribuídos, especialmente web services. Introduzido por Roy Fielding em sua tese de doutorado em 2000, REST define um conjunto de restrições que, quando aplicadas corretamente, resultam em um sistema de software que é escalável, flexível e fácil de manter.

Fonte: https://www.astera.com/pt/type/blog/rest-api-definition/

As principais restrições de REST incluem:

1. Cliente-Servidor: A arquitetura REST é baseada na separação de responsabilidades entre o cliente e o servidor. O cliente é responsável por fazer requisições e processar as respostas, enquanto o servidor é responsável por gerenciar os recursos e fornecer as respostas.
2. Stateless (Sem Estado): Cada requisição do cliente para o servidor deve conter todas as informações necessárias para entender e processar a solicitação. O servidor não mantém nenhum estado entre as requisições do cliente.
3. Cacheável: As respostas devem indicar se podem ou não ser armazenadas em cache pelo cliente. O cache melhora a eficiência da rede ao reduzir a necessidade de comunicações repetidas entre cliente e servidor.
4. Interface Uniforme: REST define uma interface uniforme entre os componentes do sistema, simplificando e desassociando a arquitetura. Isso inclui a utilização de métodos HTTP padrão (GET, POST, PUT, DELETE) e convenções de URIs.
5. Sistema em Camadas: A arquitetura pode ser composta por camadas hierárquicas, onde cada camada só interage com a camada imediatamente próxima. Isso adiciona uma estrutura modular que facilita a escalabilidade e a manutenção.
6. Code on Demand (opcional): Os servidores podem fornecer código executável ao cliente, estendendo sua funcionalidade através de scripts ou applets.

O Que é RESTful?

Uma API é considerada RESTful quando segue os princípios e restrições do estilo arquitetônico REST. Em outras palavras, uma API RESTful adere às melhores práticas e convenções de REST para fornecer um serviço web eficiente e escalável.

Características de uma API RESTful incluem:

• Uso de HTTP: As APIs RESTful utilizam métodos HTTP (GET, POST, PUT, DELETE) para realizar operações CRUD (Create, Read, Update, Delete) em recursos.
• Representação de Recursos: Recursos são representados por URIs (Uniform Resource Identifiers) e podem ser manipulados utilizando os métodos HTTP apropriados.
• Stateless: Cada requisição contém todas as informações necessárias, e o servidor não mantém estado entre requisições.
• Formato de Dados: As APIs RESTful geralmente utilizam JSON ou XML para a troca de dados entre cliente e servidor.
• HATEOAS (Hypermedia as the Engine of Application State): Opcionalmente, as respostas podem incluir links de hipertexto que permitem a navegação para outros recursos relacionados.

A Camada de Controller no NestJS

No NestJS, a camada de Controller é responsável por gerenciar as requisições HTTP e determinar como os recursos devem ser manipulados. Os controllers são uma parte fundamental do padrão MVC (Model-View-Controller) adotado pelo NestJS, onde cada controller lida com um conjunto específico de rotas e operações.

Criando um Controller no NestJS

Para iniciar voltaremos a usar o CLI do NestJS. Vamos criar um novo projeto NestJS e adicionar um controller básico:

Caso tenha dúvidas de como criar um projeto vejo o artigo anterior desse vídeo:

Curso NestJS for Azure: #1 HelloWord

após isso devemos iniciar com um comando básico

nest generate controller users

Isso criará um arquivo users.controller.ts dentro do diretório src/users. Vamos explorar como configurar este controller para criar uma API RESTful.

Configurando o Controller

No arquivo users.controller.ts, você encontrará um esqueleto básico de um controller. Vamos configurá-lo para lidar com operações CRUD para um recurso de usuários.

import { Controller, Get, Post, Put, Delete, Param, Body } from '@nestjs/common';

/**
 * Controller para gerenciar operações de usuários.
 */
@Controller('users')
export class UsersController {

  /**
   * Retorna todos os usuários.
   * 
   * @returns {string} Uma string que representa a lista de todos os usuários.
   */
  @Get()
  findAll(): string {
    // Lógica para retornar todos os usuários
    return 'Retorna todos os usuários';
  }

  /**
   * Retorna um usuário específico pelo ID.
   * 
   * @param {string} id - O ID do usuário.
   * @returns {string} Uma string que representa o usuário com o ID especificado.
   */
  @Get(':id')
  findOne(@Param('id') id: string): string {
    // Lógica para retornar um único usuário por ID
    return `Retorna o usuário com o ID ${id}`;
  }

  /**
   * Cria um novo usuário.
   * 
   * @param {any} createUserDto - Os dados do novo usuário.
   * @returns {string} Uma string que confirma a criação de um novo usuário.
   */
  @Post()
  create(@Body() createUserDto: any): string {
    // Lógica para criar um novo usuário
    return 'Cria um novo usuário';
  }

  /**
   * Atualiza um usuário existente pelo ID.
   * 
   * @param {string} id - O ID do usuário.
   * @param {any} updateUserDto - Os dados atualizados do usuário.
   * @returns {string} Uma string que confirma a atualização do usuário.
   */
  @Put(':id')
  update(@Param('id') id: string, @Body() updateUserDto: any): string {
    // Lógica para atualizar um usuário existente por ID
    return `Atualiza o usuário com o ID ${id}`;
  }

  /**
   * Deleta um usuário pelo ID.
   * 
   * @param {string} id - O ID do usuário.
   * @returns {string} Uma string que confirma a deleção do usuário.
   */
  @Delete(':id')
  remove(@Param('id') id: string): string {
    // Lógica para deletar um usuário por ID
    return `Deleta o usuário com o ID ${id}`;
  }
}

Explicação das Rotas e Métodos

Para testar as rotas do controller UsersController que configuramos no no exemplo anterior, você pode usar o curl, uma ferramenta de linha de comando para transferências de dados com sintaxe de URL. A seguir estão os comandos curl para testar cada uma das rotas (GET, POST, PUT, DELETE) do nosso controller.

• GET /users: A rota @Get() define um endpoint que responde a requisições HTTP GET na URL /users. Esse método deve retornar uma lista de todos os usuários.

curl -X GET http://localhost:3000/users

• GET /users/{id}: A rota @Get(':id') define um endpoint que responde a requisições HTTP GET na URL /users/:id, onde :id é um parâmetro dinâmico. Esse método deve retornar os detalhes de um usuário específico pelo ID (por exemplo, ID = 1):

curl -X GET http://localhost:3000/users/1

• POST /users: A rota @Post() define um endpoint que responde a requisições HTTP POST na URL /users. Para criar um novo usuário, você precisa enviar os dados do usuário no corpo da requisição. Vamos supor que os dados do usuário sejam enviados em formato JSON:

curl -X POST http://localhost:3000/users -H "Content-Type: application/json" -d '{"name": "John Doe", "age": 30}'

• PUT /users/{id}: A rota @Put(':id') define um endpoint que responde a requisições HTTP PUT na URL /users/:id. Para atualizar um usuário específico pelo ID (por exemplo, ID = 1), você também precisa enviar os dados atualizados no corpo da requisição:

curl -X PUT http://localhost:3000/users/1 -H "Content-Type: application/json" -d '{"name": "Jane Doe", "age": 25}'

• DELETE /users/{id}: A rota @Delete(':id') define um endpoint que responde a requisições HTTP DELETE na URL /users/:id. Esse método deve deletar um usuário específico com base no ID fornecido.

curl -X DELETE http://localhost:3000/users/1

Conclusão

Neste artigo, exploramos os conceitos de REST e RESTful, que são fundamentais para o desenvolvimento de APIs modernas e eficientes. Também vimos como a camada de Controller no NestJS facilita a criação de APIs RESTful, fornecendo uma estrutura organizada e poderosa para gerenciar as requisições HTTP.

Com esse conhecimento em mãos, você está pronto para continuar sua jornada com NestJS, construindo APIs robustas e escaláveis que aproveitam ao máximo os princípios de REST. No próximo artigo de nossa série, mergulharemos mais fundo em como integrar nossa API NestJS com os serviços do Azure, explorando funcionalidades avançadas e técnicas para otimizar ainda mais suas aplicações. Fique ligado!