Django REST Framework: trabalhando com validações, paginação, filtros e versionamento em uma API

Olá! Meu nome é Laís Urano, instrutora na escola de Programação da Alura, e vou te acompanhar neste curso de Django REST Framework.

Audiodescrição: Laís se descreve como uma mulher parda, de olhos castanho-escuros, e cabelos cacheados volumosos castanho-escuros com mechas azuis. Ela veste uma camisa preta, e está no estúdio da Alura, com um fundo claro iluminado em gradiente azul e verde, e uma estante preta à esquerda da instrutora com decorações e pontos de iluminação amarelas.

Para quem é este curso?

Este curso é para você que deseja aprofundar seus conhecimentos na construção de APIs utilizando o Django REST Framework.

Quais são os requisitos?

É necessário que você tenha conhecimento sobre Python e também sobre o framework Django.

Como este curso faz parte da formação Django REST APIs: crie aplicações REST em Python, recomendamos que você assista aos conteúdos anteriores ou tenha familiaridade com o projeto.

O que vamos aprender?

Neste curso, aprenderemos: a adicionar validações na API; a utilizar técnicas para lidar com um conjunto grande de dados, como paginação e filtros; e a trabalhar com versionamento.

Abordaremos tudo isso através do projeto de uma escola que irá apresentar recursos de pessoa estudante, matrícula e cursos. Vamos começar?

No curso anterior, trabalhamos na construção da API de uma escola, que consistia em criar pessoas estudantes, cursos e matrículas, além de trabalhar com essas informações.

Também criamos rotas de visualização e adicionamos uma autenticação que permitisse que apenas pessoas usuárias cadastradas acessassem e trabalhassem com essa API.

Agora temos um novo quadro no Trello, para adicionarmos alguns pontos na API com foco em integridade dos dados, segurança, e também na experiência da pessoa usuária.

Configurando o projeto

O quadro segue o mesmo esquema com quatro colunas:

1. Ferramentas;
2. Backlog;
3. Desenvolvendo;
4. Finalizado.

Na coluna de ferramentas, vamos analisar no primeiro card ("API") quais informações da API precisamos adicionar.

Informações Técnicas:

• Versão mais atual do Django REST Framework

Informações Gerais da API:

• Modelos de Estudantes, Cursos e Matrículas
• Rotas de Estudantes, Cursos, Matrículas por Estudant e Matrícula por Cursos
• Conter validações para os dados
• Adicionar técnicas para lidar com conjunto de dados (Filtros, Paginação e Ordenação)
• Uma segunda versão da API deve ser adicionada

Projeto Anterior

Manteremos a versão mais atual do Django REST Framework, e além disso, modelos e rotas permanecerão os mesmos. Ou seja, todo o projeto que construímos será reaproveitado agora.

Em seguida, começam as informações que serão o foco deste momento: primeiramente, precisamos conter validações para os dados, isto é, a API precisa adicionar um sistema de validações.

Também precisamos adicionar técnicas para lidar com conjuntos de dados. São elas: filtros, paginação e ordenação. Por fim, faremos uma segunda versão da API para ser apresentada.

Clonando o projeto anterior

Agora precisamos puxar o projeto anterior e configurar o ambiente para começarmos a trabalhar.

Primeiro, vamos clicar no link do projeto anterior, disponível na descrição do card "API". Trata-se de uma página no GitHub que contém o projeto do curso anterior, onde desenvolvemos a API.

Nessa página, vamos até "Code > Clone" para copiar a informação da URL.

https://github.com/uranolais/drf-escola-curso-01.git

Com o VS Code aberto, já temos uma pasta chamada "ESCOLA", Utilizando o atalho "Ctrl + J", vamos abrir o terminal para executar o seguinte comando:

git clone https://github.com/uranolais/drf-escola-curso-01.git .

Note que adicionamos um ponto (.) ao final do comando. Ele serve para informar que queremos copiar para o diretório atual, sem inserir uma pasta adicional.

Após finalizar, teremos acesso a todas as informações do projeto anterior.

Configurando o ambiente

O próximo passo é criar o ambiente virtual. Para isso, utilizamos o comando abaixo:

python -m venv venv

Uma vez criado o ambiente, precisamos ativá-lo para começar a trabalhar. Nesse caso, executamos o seguinte comando:

venv \Scripts\activate.bat

O comando acima é utilizado para ativar o ambiente no Windows. Caso você utilize Linux ou Mac, o comando correto será source venv/bin/activate.

Instalando as dependências da API

Com o ambiente ativado, será necessário instalar as dependências da API para começarmos a trabalhar. Iniciamos com o comando pip install. Como todas as dependências estão no arquivo requirements.txt, vamos usar o comando -r para ler esse arquivo seguido de requirements.txt.

pip install -r requirements.txt

Dessa forma, é feita a instalação de todas as dependências necessárias.

Lembre-se! Utilizaremos a versão 5.0.3 do Django e a 3.12.0 do Python, uma das versões mais atuais dessa linguagem.

Verificando o projeto

Com tudo instalado, estamos prontos para verificar o projeto. Antes de subir no servidor, precisamos verificar se há alguma migração pendente.

Para isso, vamos executar o comando a seguir:

python manage.py makemigrations

Como retorno, identificamos que não há nenhuma migração (No changes detected). Porém, se utilizarmos o comando migrate, serão feitas todas as migrações pendentes.

python manage.py migrate

Criando um superusuário

Nesse momento, poderíamos subir no servidor, mas como, teoricamente, criamos um projeto do zero, ou seja, não aproveitamos as informações iniciais, também não temos a informação de superusuário.

Sendo assim, como precisamos da autenticação, será necessário criar o superusuário para poder trabalhar com isso. Para criar o superusuário, usamos o seguinte comando:

python manage.py createsuperuser

Ao executar esse comando, serão solicitadas informações. Vamos preenchê-las seguindo o mesmo esquema de antes: o nome de usuário será lais; o endereço será [email protected]; e a senha será "lais".

Subindo o projeto no servidor

Finalmente, podemos subir no servidor, com o seguinte comando:

python manage.py runserver

Ao final, vamos copiar o link do retorno para acessar no navegador e começar a trabalhar.

http://127.0.0.1:8000/

Ao abrir a página, conseguimos utilizar as informações de usuário cadastradas para fazer login. Feito isso, teremos acesso às rotas com as quais trabalhamos anteriormente.

GET /

HTTP 200 OK
Allow: GET, HEAD, OPTIONS
Content-Type: application/json
Vary: Accept
{
"estudantes": "http://127.0.0.1:8000/estudantes/",
"cursos": "http://127.0.0.1:8000/cursos/",
"matriculas": "http://127.0.0.1:8000/matriculas/"
}

Criando novos dados

Como não salvamos nenhuma informação, precisaremos criar novos dados. Na rota de estudantes (estudantes), vamos começar criando outra pessoa estudante.

• Nome: Paula
• E-mail: [email protected]
• CPF: 01234567891
• Data de nascimento: 21/03/2024
• Celular: 8691956325

Essas são apenas sugestões de preenchimento para teste; você pode preencher conforme preferir.

Após preencher, vamos fazer o POST dessa requisição.

POST /estudantes/

HTTP 201 Created
Allow: GET, POST, HEAD, OPTIONS
Content-Type: application/json
Vary: Accept
{
"id": 1,
"nome": "Paula",
"email": "[email protected]",
"cpf": "01234567891",
"data_nascimento": "2024-03-21",
"celular": "8691956325"
}

De volta à API Root, vamos acessar a rota cursos para criar um curso.

• Código: F01
• Descrição: Curso de Flask
• Nível: Básico

Com essas informações, também vamos realizar o POST.

POST /cursos/

HTTP 201 Created
Allow: GET, POST, HEAD, OPTIONS
Content-Type: application/json
Vary: Accept
{
"id": 1,
"codigo": "F01",
"descricao": "Curso de Flask",
"nivel": "B"
}

Feito isso, há um detalhe na nossa API: se voltarmos na rota estudantes e copiarmos o CPF da Paula, conseguimos criar outra pessoa estudante com dados diferentes e o mesmo CPF. Por exemplo:

• Nome: Ju
• E-mail: [email protected]
• CPF: 01234567891
• Data de nascimento: 30/03/2024
• Celular: 61582516385

Ao fazer o POST, temos a seguinte resposta da requisição:

HTTP 201 Created
Allow: GET, POST, HEAD, OPTIONS
Content-Type: application/json
Vary: Accept
{
"id": 2,
"nome": "Ju",
"email": "[email protected]",
"cpf": "01234567891",
"data_nascimento": "2024-03-30",
"celular": "61582516385"
}

Ele não fez nenhuma verificação, então agora o sistema tem duas pessoas estudantes com o mesmo CPF. Isso não é seguro, pois podem acontecer erros e cadastrarmos várias pessoas estudantes com o mesmo dado de CPF, ou celular, por exemplo, e essas informações não deveriam estar repetidas no banco.

Vamos acessar o endereço http://127.0.0.1:8000/estudantes/2/ para excluir a pessoa estudante de id igual a 2 e evitar problemas na API futuramente.

Conclusão

Nesse cenário, precisamos adicionar algumas validações. A partir do próximo vídeo, começaremos a trabalhar na inclusão dessas validações no nosso sistema!

Para evitar o cadastro de valores duplicados ou inapropriados na API, precisamos validar esses valores. Existem várias maneiras de fazer isso, mas no nosso caso, a primeira maneira exibida na coluna de backlog do quadro no Trello é através do próprio Model.

Definindo o valor único de dados

Ao acessar o card "Model - Estudantes" no Trello, identificamos que, de certa forma, já realizamos algumas validações.

Validações necessárias:

• E-mail
  • Não pode estar em branco
• CPF
  • Máximo de 11 caracteres
  • Valor Único
• Número de Celular
  • Máximo de 14 caracteres

Por exemplo: uma das validações listadas é que o e-mail não pode estar em branco, e já incluímos isso anteriormente. O CPF deve ter, no máximo, 11 caracteres, enquanto o número de celular precisa ter, no máximo, 14 caracteres. Essas validações também foram adicionadas em etapas anteriores.

No entanto, há uma validação que ainda precisa ser feita: o CPF precisa ser um valor único.

Adicionando o parâmetro unique

De volta ao VS Code, vamos abrir o arquivo models.py na pasta "escola".

Nesse arquivo, já temos todas as validações para definir o tamanho máximo de cada informação, definir que determinada informação não pode estar em branco, e assim por diante.

No cpf da linha 6, precisamos adicionar um parâmetro a mais: o unique, que será igual a True.

models.py:

from django.db import models
class Estudante(models.Model):
nome = models.CharField(max_length = 100)
email = models.EmailField(blank = False, max_length = 30)
cpf = models.CharField(max_length = 11, unique=True)
data_nascimento = models.DateField()
celular = models.CharField(max_length = 14)

O que essa informação adicional faz? No momento que cadastramos a pessoa estudante, ele irá verificar se existe um CPF igual àquele no banco de dados. Se existir, não será permitida a criação. Caso não exista, será permitido. Ou seja, o valor de cpf precisa ser único no banco de dados.

Realizando as migrações

Feito isso, vamos utilizar o atalho "Ctrl + J" para abrir o terminal, onde faremos as migrações para testar a informação. Executaremos os seguintes comandos:

python manage.py makemigrations

python manage.py migrate

Testando dados duplicados

Agora vamos acessar o servidor e fazer o mesmo teste de antes: copiar o CPF de uma pessoa estudante já existente no banco de dados, e tentar criar outra pessoa estudante com o mesmo número de CPF.

De volta à rota de estudantes no navegador (http://127.0.0.1:8000/estudantes/), vamos copiar o CPF da Paula, estudante que criamos anteriormente, e colar no formulário abaixo.

Junto a isso, passaremos as seguintes informações:

• Nome: Ju
• E-mail: [email protected]
• CPF: 01234567891
• Data de nascimento: 21/03/2024
• Celular: 51658452

Essas são apenas sugestões de preenchimento para teste; você pode preencher conforme preferir.

Ao enviar essa informação, recebemos a seguinte resposta:

HTTP 400 Bad Request
Allow: GET, POST, HEAD, OPTIONS
Content-Type: application/json
Vary: Accept
{
"cpf": [
"estudante com este cpf já existe."
]
}

Dessa forma, temos nossa validação em funcionamento.

Verificando a interpretação dos dados

Como isso é observado do ponto de vista do código? Vamos voltar para o VS Code e abrir o Shell novamente no terminal, utilizando o comando a seguir:

python manage.py shell

Na sequência, vamos puxar tanto o modelo (models) quanto o serializador (serializers), para entendermos como esses dados são interpretados. Para isso, executaremos os seguintes comandos:

from escola.models import Estudante
from escola.serializers import EstudanteSerializer

Na sequência, queremos passar uma informação para testar o dado recebido. Para isso, vamos adicionar apenas o comando s e puxar após = uma instância do serializador, ou seja, EstudanteSerializer().

from escola.models import Estudante
from escola.serializers import EstudanteSerializer
s = EstudanteSerializer()

Por fim, queremos observar o que está no escopo do objeto, então vamos adicionar o método print() ao final e utilizar repr(s) entre parênteses, função própria do Python para observar o que é passado.

from escola.models import Estudante
from escola.serializers import EstudanteSerializer
s = EstudanteSerializer()
print(repr(s))

Como retorno, recebemos as seguintes informações:

EstudanteSerializer():
    id = IntegerField(label='ID', read_only=True)
    nome = CharField(max_length=100)
    email = EmailField(max_length=30)
    cpf = CharField(max_length=11, validators=[<UniqueValidator(queryset=Estudante.objects.all())>])
    data_nascimento = DateField()
    celular = CharField(max_length=14)

Inicialmente, temos a informação de id. Como sabemos, não criamos o id, então ele está definido apenas como leitura. Na sequência, temos todas as informações definidas anteriormente: se definimos em código que o tamanho máximo do e-mail precisava ser 30 caracteres, esse dado estará informado.

Note que no cpf, temos o parâmetro validators, ou seja, o parâmetro unique, que define que um valor deve ser único, é um validators.

Conclusão

Agora que validamos a informação de CPF, podemos validar os outros dados do modelo. Faremos isso no próximo vídeo!