rest-api-crud

rest-api-crud.mp4

Nesse repositório estarei explicando, de uma maneira simples, o passo a passo para criar uma REST API, utilizando o Django e o Django REST framework. Optei por escrever esse tutorial em português, pois é um tópico bastante requisitado e que não se encontra tanto conteúdo assim no nosso idioma.

Para facilitar a sua leitura e o seu entendimento, dividi esse tutorial em alguns passos.

1. Iniciando o projeto Django.
2. Iniciando uma aplicação.
3. Instalando o Django REST framework.
4. Criando o modelo.
5. Migrando as aplicações.
6. Definindo serializers.
7. Definindo viewsets.
8. Definindo routers.

IMPORTANTE: Para acompanhar esse passo a passo, recomenda-se ter um conhecimento mínimo em Django, pois passarei direto por algumas explicações de conceitos básicos, tendo em mente que você, leitor, sabe o que está acontecendo.

1. Iniciando o projeto Django

Para iniciar um novo projeto, primeiramente você deve ter o framework Django instalado em sua máquina (no momento em que estou escrevendo isso, a versão mais recente é a 3.2, recomendo que instale essa, ou caso exista, uma superior, sempre preferindo trabalhar em um ambiente virtual próprio para o projeto), para instalá-lo você pode simplesmente digitar em seu terminal:

pip install django

Depois de instalar o Django, você deverá criar o seu projeto, no meu caso, o chamarei de myproject.

django-admin startproject myproject

2. Iniciando uma aplicação

Depois do projeto ter sido criado, você deverá entrar no diretório do mesmo, pois lá encontra-se o arquivo manage.py e é com ele que faremos praticamente tudo a partir de agora.

cd myproject

Com esse arquivo, estarei criando uma aplicação chamada myapi.

python manage.py startapp myapi

A diferença entre um projeto e uma aplicação nem sempre é muito bem entendida por quem está começando, uma ótima definição está presente na própria documentação em português do Django.

Qual é a diferença entre um projeto e uma aplicação? Uma aplicação é um conjunto de elementos web que faz alguma coisa - por exemplo, um sistema de blog, um banco de dados de registros públicos, ou uma pequena aplicação de enquetes. Um projeto é uma coleção de configurações e aplicações para um website particular. Um projeto pode conter múltiplas aplicações. Uma aplicação pode estar em múltiplos projetos. Em Django, chamamos uma aplicação de “app”.

Logo após a criação da sua aplicação, você deverá adicioná-la ao projeto, acessando as configurações do projeto myproject/settings.py e a acrescentando na lista INSTALLED_APPS, assim o Django saberá que essa aplicação faz parte do projeto.

INSTALLED_APPS = [
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    'myapi.apps.MyapiConfig', # A aplicação que você acabou de criar
]

As aplicações já presentes nessa lista são padrões do Django, fique a vontade para remover as que não são úteis para você.

3. Instalando o Django REST framework

Agora que o projeto e a aplicação foram criados, vamos instalar o Django REST framework.

pip install djangorestframework

E já adicioná-lo na lista das aplicações do nosso projeto, repetindo o processo final do item anterior.

INSTALLED_APPS = [
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    'myapi.apps.MyapiConfig',
    'rest_framework', # Django REST framework
]

Simples assim, a ferramenta que você irá utilizar para construir suas REST APIs no Django, está pronta para uso.

4. Criando o modelo

Para facilitar todo o entendimento, e como a criação de modelos e a configuração de bancos de dados não é o nosso foco, usarei o banco de dados padrão do Django (SQLite) e criarei um modelo bem simples.

O modelo que irei criar se chamará Person (pessoa) e contará com quatro campos (cinco, considerando o id): Name (o nome da pessoa), Age (a idade da pessoa), Country (o país em que essa pessoa vive atualmente) e Programmer (se essa pessoa trabalha ou não com programação). Como sabemos, modelos são criados no arquivo models.py das aplicações (no meu caso myapi/models.py), herdando a classe django.db.models.Model.

from django.db import models


class Person(models.Model):
    name = models.CharField(max_length=100)
    age = models.PositiveSmallIntegerField()
    country = models.CharField(max_length=100)
    programmer = models.BooleanField()

Note que os campos que criamos são atributos da classe, cada campo é uma coluna no nosso banco de dados, mas do jeito que está agora ele não tem quase nenhuma utilidade. Precisamos migrá-lo para o nosso projeto de fato.

5. Migrando as aplicações

Antes de migrar as aplicações, tente rodar localmente o servidor e veja o que acontece.

python manage.py runserver

Um aviso aparece:

You have 18 unapplied migration(s). Your project may not work properly until you apply
the migrations for app(s): admin, auth, contenttypes, sessions.
Run 'python manage.py migrate' to apply them.

Todas essas aplicações, que já foram vistas anteriormente como sendo as padrões do Django, estão prontas para serem migradas para o projeto com um simples migrate, note que a criada por você não está aí. Usaremos o makemigrations para isso. Nesse caso, esse comando dirá ao Django que temos um novo modelo e queremos que ele fique salvo como uma migração.

python manage.py makemigrations

Agora rode o servidor novamente e veja o novo aviso que aparece.

You have 19 unapplied migration(s). Your project may not work properly until you apply
the migrations for app(s): admin, auth, contenttypes, myapi, sessions.
Run 'python manage.py migrate' to apply them.

Sua aplicação agora está ali, e o seu modelo pronto para ser migrado. Observe que o diretório myapi/migrations foi criado, e dentro dele existe o arquivo 0001_initial.py.

from django.db import migrations, models


class Migration(migrations.Migration):

    initial = True

    dependencies = [
    ]

    operations = [
        migrations.CreateModel(
            name='Person',
            fields=[
                ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
                ('name', models.CharField(max_length=100)),
                ('age', models.PositiveSmallIntegerField()),
                ('country', models.CharField(max_length=100)),
                ('programmer', models.BooleanField()),
            ],
        ),
    ]

Esse é o modelo que criei, (caso você tenha seguido os mesmos passos até aqui, estará assim para você também) salvo e pronto para ser migrado. Caso você tenha alguma experiência com o git, o comando makemigrations do Django funciona da mesma forma que o add, assim como o migrate, que usaremos agora para migrar de fato as aplicações para o projeto, e o commit.

Digite então em seu terminal:

python manage.py migrate

6. Definindo serializers

Para explicar a função dos serializers adicionarei dois registros no banco de dados criado, pelo próprio terminal do Django. Para isso, utilizarei o comando python manage.py shell.

python manage.py shell

>>> from myapi.models import Person
>>> person1 = Person(name='João', age=22, country='Brazil', programmer=False)
>>> person1.save()
>>> person2 = Person(name='Maria', age=25, country='Brazil', programmer=True)
>>> person2.save()
>>> Person.objects.all()

<QuerySet [<Person: Person object (1)>, <Person: Person object (2)>]>

Você provalvelmente entendeu o que aconteceu, importei o nosso modelo, que é uma classe, criei duas instâncias (person1 e person2) e utilizei o método save() para salvá-las como registros no nosso banco de dados, após isso, visualizei todos os objetos presentes no nosso banco de dados com Person.objects.all(), e foi retornada uma QuerySet, que é um tipo de dado não nativo do Python, os serializers nos permitem transformar esse tipo de dado em, por exemplo, json (realizar o caminho contrário também é possível, no caso seria um deserializers).

Para isso, crie um arquivo, no diretório da sua aplicação, chamado serializers.py, nele você importará o módulo serializer do Django REST framework e os seus modelos.

from rest_framework import serializers
from . import models


class PersonSerializer(serializers.ModelSerializer):
    class Meta:
        model = models.Person
        fields = '__all__'

Note que o nome da classe é a junção do nome do modelo que criei e Serializer (é apenas uma convenção, não necessária mas importante), e herda a classe rest_framework.serializers.ModelSerializer. Dentro dela, você deverá criar uma classe Meta e definir dois atributos: model (o seu modelo) e fields (nesse caso eu utilizei __all__ para pegar todos os campos do meu banco de dados, mas você pode escolher manualmente, especificando-os em uma tupla).

7. Definindo viewsets

Você poderia muito bem, após transformar seus dados com os serializers, utilizar as views padrões do Django para retornar esses mesmos dados ao usuário, mas isso não seria muito prático. A classe rest_framework.viewsets.ModelViewSet que herdamos para construir as viewsets já nos disponibiliza métodos para que não precisemos contruí-los do zero, alguns deles:

• list() - corresponde ao método GET, que simplesmente lista os objetos.
• create() - corresponde ao método POST, que te permite criar um novo objeto.
• update() - corresponde ao método PUT, que te permite atualizar as informações de um objeto ja existente.
• destroy() - corresponde ao método DELETE, que te permite deletar algum objeto.

Para isso, crie, no mesmo diretório do serializers.py, um arquivo chamado viewsets.py. Nele, importe o necessário e crie a sua classe, note que novamente utilizei uma convenção para nomear minha classe. Note também que o Person.objects.all() aparece mais uma vez, sendo atribuído a um atributo da classe, chamado queryset (volte e releia o início do passo 6), e em serializer_class você deve passar sua classe serializer responsável pela transformação desses dados.

from rest_framework import viewsets
from . import serializers
from . import models


class PersonViewSets(viewsets.ModelViewSet):
    queryset = models.Person.objects.all()
    serializer_class = serializers.PersonSerializer

8. Definindo routers

Como estamos usando viewsets, não é preciso definir as configurações de rotas manualmente, a classe rest_framework.routers.DefaultRouter fará isso para nós, basta que você a importe, a instancie, e registre as suas viewsets.

Para isso, crie o arquivo routers.py no diretório do seu projeto (no meu caso myproject/routers.py).

from rest_framework import routers
from myapi import viewsets

router = routers.DefaultRouter()
router.register('myapi', viewsets.PersonViewSets)

Após isso, vá para myproject/urls.py, e importe a função include do módulo django.urls. Você deverá adicionar mais um item na lista urlpatterns. Note que o projeto agora incluirá as suas rotas registradas no passo anterior.

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

urlpatterns = [
    path('admin/', admin.site.urls),
    path('api/', include(routers.router.urls)),
]

Agora é só rodar o servidor e pronto, você acabou de construir uma REST API com os métodos Create, Read, Update e Delete.