Ao construir APIs RESTful com Django e o poderoso Django REST Framework (DRF), é fundamental entender como estruturar as views que processam as requisições HTTP. O DRF oferece o decorador @api_view, uma ferramenta versátil para transformar funções regulares do Django em views de API que podem lidar com diferentes métodos HTTP (GET, POST, PUT, DELETE, etc.) de forma controlada e eficeinte. Este guia detalha o uso de @api_view para implementar as operações básicas de um CRUD (Criar, Ler, Atualizar, Deletar) para um recurso simples, como "Produto".

Para este exemplo, assumimos que você já possui um projeto Django configurado com uma aplicação chamada gerenciamento_api. Dentro desta aplicação, temos um modelo Produto (com campos como nome, descricao, preco, etc.) definido em models.py e um ProdutoSerializer correspondente em serializers.py para serializar e desserializar instâncias de Produto.

Implementando a View para Listagem e Criação

A primeira view que criaremos será responsável por listar todos os produtos existentes ou adicionar um novo produto ao banco de dados. Esta funcionalidade geralmente reside em um endpoint de coleção.

No arquivo gerenciamento_api/views.py, adicione o seguinte código:

from rest_framework import status
from rest_framework.decorators import api_view
from rest_framework.response import Response

from .models import Produto
from .serializers import ProdutoSerializer

@api_view(['GET', 'POST'])
def colecao_produtos_view(request):
    """
    Manipula requisições GET para listar todos os produtos e POST para criar um novo produto.
    """
    if request.method == 'GET':
        itens = Produto.objects.all()
        serializador = ProdutoSerializer(itens, many=True)
        return Response(serializador.data)
    
    elif request.method == 'POST':
        serializador = ProdutoSerializer(data=request.data)
        if serializador.is_valid():
            serializador.save()
            return Response(serializador.data, status=status.HTTP_201_CREATED)
        return Response(serializador.errors, status=status.HTTP_400_BAD_REQUEST)

Nesta view, o decorador @api_view(['GET', 'POST']) indica que a função colecao_produtos_view deve responder apenas a requisições GET e POST. O DRF automaticamente converte o objeto HttpRequest padrão do Django em um Request do DRF, fornecendo acesso a request.data para o corpo da requisição e facilitando o manuseio de diferentes formatos de mídia. A classe Response do DRF é utilizada para retornar dados serializados ou erros com códigos de status HTTP apropriados.

Configurando as URLs para a Coleção de Produtos

Para que a view seja acessível, precisamos associá-la a uma URL. Crie ou edite o arquivo gerenciamento_api/urls.py:

from django.urls import path
from . import views

urlpatterns = [
    path('produtos/', views.colecao_produtos_view, name='lista_cria_produtos'),
]

Em seguida, inclua as URLs da sua aplicação no arquivo principal de URLs do projeto (geralmente projeto_raiz/urls.py):

from django.contrib import admin
from django.urls import path, include

urlpatterns = [
    path('admin/', admin.site.urls),
    path('api/', include('gerenciamento_api.urls')), # Inclui as URLs da sua app
]

Testando a View de Listagem e Criação

Após configurar a view e as URLs, inicie o servidor de desenvolvimento Django:

python manage.py runserver 0.0.0.0:8000

• **Requisição GET (Listar Produtos):**Envie uma requisição GET para http://localhost:8000/api/produtos/.

  A API retornará um array JSON contendo todos os produtos no banco de dados.

• **Requisição POST (Criar Produto):**Envie uma requisição POST para http://localhost:8000/api/produtos/ com um corpo JSON representando o novo produto:

  {
     "nome": "Smartphone X100",
     "descricao": "Celular de última geração com câmera 108MP.",
     "preco": 1299.99,
     "em_estoque": true
  }
  
  

  Se os dados forem válidos, você receberá uma resposta com o produto criado e o status 201 Created. Caso contrário, um status 400 Bad Request será retornado com os erros de validação.

Implementando a View para Detalhes, Atualização e Exclusão

Para interagir com um único produto — recuperá-lo, atualizá-lo ou excluí-lo — criaremos uma view de detalhes que aceita um ID de produto na URL.

Adicione a seguinte função em gerenciamento_api/views.py:

@api_view(['GET', 'PUT', 'DELETE'])
def detalhes_produto_view(request, produto_id):
    """
    Recupera, atualiza ou exclui um produto específico pelo seu ID.
    """
    try:
        produto = Produto.objects.get(id=produto_id)
    except Produto.DoesNotExist:
        return Response(status=status.HTTP_404_NOT_FOUND)

    if request.method == 'GET':
        serializador = ProdutoSerializer(produto)
        return Response(serializador.data)

    elif request.method == 'PUT':
        serializador = ProdutoSerializer(produto, data=request.data, partial=False)
        if serializador.is_valid():
            serializador.save()
            return Response(serializador.data)
        return Response(serializador.errors, status=status.HTTP_400_BAD_REQUEST)

    elif request.method == 'DELETE':
        produto.delete()
        return Response(status=status.HTTP_204_NO_CONTENT)

Esta view utiliza @api_view(['GET', 'PUT', 'DELETE']) para permitir as operações de leitura, atualização completa e exclusão. Primeiramente, tenta-se localizar o produto pelo produto_id fornecido. Se não for encontrado, retorna-se 404 Not Found. Para uma requisição PUT, o ProdutoSerializer é instanciado com o objeto existente e os novos dados, garantindo que o objeto correto seja atualizado. Para DELETE, o produto é simplesmente removido, retornando 204 No Content, que indica sucesso sem conteúdo de resposta.

Configurando as URLs para a View de Detalhes

Adicione a rota para a view de detalhes em gerenciamento_api/urls.py:

from django.urls import path
from . import views

urlpatterns = [
    path('produtos/', views.colecao_produtos_view, name='lista_cria_produtos'),
    path('produtos/<int:produto_id>/', views.detalhes_produto_view, name='detalhes_produto'),
]

A notação <int:produto_id> é um conversor de caminho do Django que captura um valor inteiro da URL e o passa como argumento produto_id para a view.

Testando a View de Detalhes, Atualização e Exclusão

Com o servidor de desenvolvimento em execução, você pode testar as operações de detalhes:

• **Requisição GET (Recuperar Detalhes):**Para obter os detalhes de um produto específico, envie uma requisição GET para http://localhost:8000/api/produtos/<ID_DO_PRODUTO>/ (substitua <ID_DO_PRODUTO> pelo ID real de um produto).

  Exemplo: http://localhost:8000/api/produtos/1/

  A API retornará os dados JSON do produto correspondente.

• **Requisição PUT (Atualizar Produto):**Para atualizar um produto existente, envie uma requisição PUT para http://localhost:8000/api/produtos/<ID_DO_PRODUTO>/ com o corpo JSON contendo os dados atualizados:

  {
     "nome": "Smartphone X100 Pro",
     "descricao": "Versão aprimorada com bateria de maior duração.",
     "preco": 1399.99,
     "em_estoque": false
  }
  
  

  Se a atualização for bem-sucedida, a API retornará o objeto de produto atualizado. Caso os dados sejam inválidos, você receberá um 400 Bad Request.

• **Requisição DELETE (Excluir Produto):**Para remover um produto, envie uma requisição DELETE para http://localhost:8000/api/produtos/<ID_DO_PRODUTO>/.

  Uma resposta com status 204 No Content indica que o produto foi excluído com sucesso.

Utilizando o decorador @api_view, você pode facilmente construir APIs RESTful robustas e flexíveis com views baseadas em função, controlando precisamente quais métodos HTTP são permitidos e como cada um deles deve ser tratado.