Boas Práticas em API REST: Explorando os Verbos HTTP com Exemplos em C#

Introdução

Olá, devs! APIs REST são a espinha dorsal da comunicação na web moderna.

Neste post, vamos explorar as melhores práticas para criar APIs RESTful e entender as diferenças entre os verbos HTTP com exemplos práticos em C#.

Vamos usar como exemplo uma estrutura de pedidos e itens, para tornar tudo mais prático e aplicável ao seu dia a dia de desenvolvimento.

Bora?

REST API

O que é uma API REST?

Uma API REST (Representational State Transfer) é um conjunto de regras que permite a comunicação entre sistemas usando o protocolo HTTP.

Elas são amplamente utilizadas devido à sua simplicidade e à capacidade de integrar diferentes sistemas de maneira eficiente.

Principais características de uma API RESTful:

  • Stateless: Cada chamada da API contém todas as informações necessárias para o servidor entender e processar a solicitação;
  • Uniform Interface: Define um contrato consistente para a API, geralmente utilizando endpoints previsíveis e métodos HTTP padrão;
  • Client-Server Architecture: A arquitetura divide o cliente (interface do usuário) e o servidor (backend e banco de dados) para promover a escalabilidade;

Boas Práticas para APIs REST

Design de Endpoints:

  • Use substantivos para os endpoints e verbos para os métodos HTTP. Por exemplo, /pedidos para acessar pedidos;
  • Siga um padrão de URL consistente. Por exemplo, /pedidos/{pedidoId}/itens para acessar itens de um pedido específico;

Versionamento de API:

  • Inclua a versão da API na URL, como /api/v1/pedidos, para facilitar a manutenção e atualização;

Autenticação e Autorização:

  • Utilize tokens JWT para autenticação;
  • Implemente controle de acesso para garantir que os usuários só possam acessar recursos para os quais têm permissão;

Tratamento de Erros:

  • Utilize códigos de status HTTP apropriados;
  • Forneça mensagens de erro claras e detalhadas;

Verbos HTTP e suas Utilizações

GET: Recuperação de dados

  • Usado para recuperar informações de um recurso;
  • Exemplo: GET /pedidos para listar todos os pedidos;

POST: Criação de novos recursos

  • Usado para criar um novo recurso;
  • Exemplo: POST /pedidos para criar um novo pedido;

PUT: Atualização de recursos existentes

  • Usado para substituir um recurso existente;
  • Exemplo: PUT /pedidos/{id} para atualizar um pedido completo;

PATCH: Atualização parcial de recursos

  • Usado para atualizar parcialmente um recurso;
  • Exemplo: PATCH /pedidos/{pedidoId}/itens/{itemId} para atualizar um campo específico de um item de pedido;

DELETE: Remoção de recursos

  • Usado para remover um recurso;
  • Exemplo: DELETE /pedidos/{pedidoId}/itens/{itemId} para deletar um item de um pedido;

Exemplos de Código em C#

Vamos ver um exemplo simples e prático de como implementar Rest API em um projeto C#

  • Pedidos: 
[ApiController]
[Route("api/v1/pedidos")]
public class PedidosController : ControllerBase
{
    [HttpGet]
    public async Task<IActionResult> GetPedidos()
    {
        // Chamar a lógica de recuperação de pedidos
        return Ok(/* lista de pedidos */);
    }

    [HttpPost]
    public async Task<IActionResult> CreatePedido([FromBody] Pedido pedido)
    {
        // Chamar a lógica de criação de pedido
        return CreatedAtAction(nameof(GetPedidoById), new { id = pedido.Id }, pedido);
    }

    [HttpGet("{id}")]
    public async Task<IActionResult> GetPedidoById(int id)
    {
        // Chamar a lógica de recuperação de pedido por ID
        return Ok(/* pedido */);
    }

    [HttpPut("{id}")]
    public async Task<IActionResult> UpdatePedido(int id, [FromBody] Pedido pedidoAtualizado)
    {
        if (id != pedidoAtualizado.Id)
        {
            return BadRequest();
        }

        // Chamar a lógica de atualização de pedido

        return NoContent();
    }
}
  • Itens: 
[ApiController]
[Route("api/v1/pedidos/{pedidoId}/itens")]
public class ItensController : ControllerBase
{
    [HttpGet]
    public async Task<IActionResult> GetItens(int pedidoId)
    {
        // Chamar a lógica de recuperação de itens do pedido
        return Ok(/* lista de itens */);
    }

    [HttpPatch("{itemId}")]
    public async Task<IActionResult> UpdateItemParcial(int pedidoId, int itemId, [FromBody] JsonPatchDocument<Item> patchDoc)
    {
        if (patchDoc == null)
        {
            return BadRequest();
        }

        // Chamar a lógica de atualização parcial de item

        return NoContent();
    }

    [HttpDelete("{itemId}")]
    public async Task<IActionResult> DeleteItem(int pedidoId, int itemId)
    {
        // Chamar a lógica de deleção de item

        return NoContent();
    }
}

Conclusão

Seguir as melhores práticas para desenvolver APIs RESTful é essencial para criar sistemas robustos e eficientes.

Entender e utilizar corretamente os verbos HTTP, juntamente com uma boa estrutura de código, garantirá que sua API seja fácil de manter e escalar.

Esperamos que esses exemplos em C# ajudem você a implementar suas próprias APIs de maneira eficaz.

Agora que você conhece um pouco mais sobre Rest APIs, me conte mais o que achou. Gostou?

Até!

Subscribe
Subscribe