Resumo : neste tutorial, você aprenderá sobre o Django REST Framework e como usá-lo para criar uma API RESTful simples, mas completa, que gerencia todos.
Introdução ao framework REST do Django
Django REST Framework ou DRF é um kit de ferramentas poderoso para desenvolver APIs Web em aplicativos Django. O DRF permite criar APIs RESTful rapidamente , fornecendo classes e convenções pré-construídas.
O DRF possui os seguintes recursos principais:
- Serialização: A serialização permite converter automaticamente modelos Django para JSON e vice-versa, tornando a transferência de dados entre cliente e servidor perfeita.
- Roteamento de URL: DRF fornece roteamento de URL igual ao roteador do Django, o que permite associar URLs às suas visualizações de API de forma eficiente.
- Autenticação: DRF oferece vários métodos de autenticação, incluindo autenticação básica e autenticação de token. Ele também oferece suporte a JWT por meio de um pacote de terceiros.
- Permissão : o DRF permite um controle refinado sobre as permissões do usuário.
- Limitação de aceleração/taxa: os recursos de otimização e taxa ajudam a limitar o número de solicitações que um cliente pode fazer em um determinado período de tempo.
- Paginação: o DRF fornece suporte integrado para paginação de grandes conjuntos de dados em respostas de API.
- API navegável: DRF possui uma interface HTML amigável para testar e explorar APIs diretamente do navegador.
Continuaremos o projeto Todo que paramos no tutorial anterior . Para começar, você pode baixar o projeto através deste link .
Instalando o pacote Django REST Framework
Primeiro, instale o framework Django REST no ambiente virtual do projeto:
pip install djangorestframework
Linguagem de código: texto simples ( texto simples )
Segundo, atualize o requirements.txt
arquivo:
pip freeze > requirements.txt
Linguagem de código: texto simples ( texto simples )
Terceiro, registre rest_framework
o aplicativo no settings.py
projeto:
INSTALLED_APPS = [
...
'rest_framework',
...
]
Linguagem de código: Python ( python )
Criando um novo aplicativo de estrutura Django REST
Primeiro, crie um novo diretório chamado api
no diretório do projeto para hospedar o código da API:
mkdir api
Linguagem de código: texto simples ( texto simples )
Segundo, crie três arquivos Python dentro do api
diretório:
serializers.py
– fornece um serializador que converte os modelos do Django para o formato JSON e vice-versa.views.py
– abriga as visualizações da API, semelhantes às visualizações do aplicativo Django.urls.py
– define o endpoint da API que mapeia para as visualizações da API.
Terceiro, adicione api
no INSTALLED_APPS
arquivo settings.py
do projeto:
INSTALLED_APPS = [
...
'api',
...
]
Linguagem de código: Python ( python )
Criaremos uma API com os seguintes endpoints:
Pontos finais | Verbo HTTP | Descrição |
---|---|---|
api/v1/todos/ |
GET |
Retornar todos todos |
api/v2/todos/ |
POST |
Crie uma nova tarefa |
api/v2/todos/1 |
GET |
Retorne a tarefa com o id 1 |
api/v1/todos/1 |
PATCH |
Atualize a tarefa com id 1 |
api/v1/todos/1 |
DELETE |
Exclua a tarefa com id 1 |
Criando uma classe serializadora
As classes serializadoras permitem serializar as instâncias do modelo do Django em JSON e vice-versa.
O seguinte define uma classe serializador chamada TodoSerializer
no serializers.py
arquivo que serializa a Todo
instância para JSON e vice-versa:
from rest_framework import serializers
from todo.models import Todo
class TodoSerializer(serializers.ModelSerializer):
user = serializers.StringRelatedField(read_only=True)
class Meta:
model = Todo
fields = ('id', 'title', 'completed', 'user')
Linguagem de código: Python ( python )
Como funciona.
Primeiro, importe o serializers
módulo do rest_framework
pacote:
from rest_framework import serializers
Linguagem de código: Python ( python )
Segundo, importe o Todo
modelo do models
módulo do todo
aplicativo:
from todo.models import Todo
Linguagem de código: Python ( python )
Terceiro, defina a TodoSerializer
classe que estende a serializers.ModelSerializer
classe:
class TodoSerializer(serializers.ModelSerializer):
...
Linguagem de código: Python ( python )
Fornece ModelSerializer
uma maneira rápida de definir uma classe serializadora com campos correspondentes aos campos do modelo.
Dentro da TodoSerializer
classe, defina uma Meta
classe que inicialize:
model
– especifica oTodo
modelo.fields
– especifica uma lista de campos para o serializador. Se o serializador usar todos os campos do modelo, você poderá usar o'__all__'
, assim:
fields = '__all__'
Linguagem de código: JavaScript ( javascript )
Como o Todo
modelo está associado ao User
modelo, especificamos o user
atributo como StringRelatedField()
e definimos seu parâmetro como read_only
.
Isso significa que the Todo
terá a representação em string do User
which é the username
neste caso.
O read_only
parâmetro permite que o serializador leia apenas o User
modelo. Em outras palavras, o serializador não poderá atualizar o User
modelo.
Além do StringRelatedField
, o DRF fornece outros tipos de campos relacionados conforme mostrado na tabela a seguir:
Campo | Descrição |
---|---|
PrimaryKeyRelatedField |
Represente o modelo relacionado como a chave primária. |
HyperlinkedRelatedField |
Represente o modelo relacionado como um hiperlink. |
SlugRelatedField |
Represente o modelo relacionado como um de seus campos. |
HyperlinkedIdentityField |
Represente o modelo relacionado como um hiperlink para o campo de identidade. |
Como concluímos a definição da classe Serializer, vamos usá-la para serializar o modelo Todo usando a classe TodoSerializer no Django Shell.
Serializando dados
Primeiro, inicie o Django Shell a partir do terminal:
python manage.py shell
Linguagem de código: CSS ( css )
Segundo, importe o Todo
modelo e TodoSerializer
a classe:
>>> from api.serializers import TodoSerializer
>>> from todo.models import Todo
Linguagem de código: JavaScript ( javascript )
Terceiro, obtenha o Todo
com id 1:
>> todo = Todo.objects.get(id=1)
>>> todo
<Todo: Learn Python>
Linguagem de código: Python ( python )
Quarto, crie uma nova instância com o TodoSerializer
modelo Todo
e acesse o atributo data:
>>> serializer = TodoSerializer(todo)
>>> serializer.data
{'id': 1, 'title': 'Learn Python', 'completed': False, 'user': 'john'}
Linguagem de código: Python ( python )
O TodoSerialzier
objeto serializa o modelo de tarefas no formato JSON.
Criando uma classe de visualização de API
O seguinte define classes de visualização de API no views.py
arquivo:
from rest_framework import generics
from .serializers import TodoSerializer
from todo.models import Todo
class TodoList(generics.ListCreateAPIView):
queryset = Todo.objects.all()
serializer_class = TodoSerializer
def perform_create(self, serializer):
serializer.save(user=self.request.user)
class TodoDetail(generics.RetrieveUpdateDestroyAPIView):
queryset = Todo.objects.all()
serializer_class = TodoSerializer
Linguagem de código: Python ( python )
Como funciona.
Primeiro, importe generics
do rest_framework
:
from rest_framework import generics
Linguagem de código: Python ( python )
Eles generics
fornecem várias classes de visualização base, como ListCreateAPIView
e RetrieveUpdateDestroyAPIView
.
Em segundo lugar, importe o TodoSerializer
do serializers
aplicativo api
e Todo
o modelo do models
aplicativo todo
:
from .serializers import TodoSerializer
from todo.models import Todo
Linguagem de código: Python ( python )
Terceiro, defina a TodoList
classe que estende a ListCreateAPIView
classe. A TodoList
turma é responsável por duas tarefas:
- Liste todos todos.
- Crie uma nova tarefa.
class TodoList(generics.ListCreateAPIView):
queryset = Todo.objects.all()
serializer_class = TodoSerializer
def perform_create(self, serializer):
serializer.save(user=self.request.user)
Linguagem de código: Python ( python )
Na TodoList
classe, especifique o queryset
usado para retornar todos todos e serializer_class
usado para serialização/desserialização das Todo
instâncias.
O perform_create()
método da classe TodoSerializer é invocado automaticamente quando você salva uma nova instância Todo.
Como cada Todo
instância precisa de uma User
instância, atribuímos o valor user
da solicitação HTTP ( request
) ao user
atributo da Todo
instância antes de salvá-la no banco de dados.
Finalmente, defina a TodoDetail
classe que estende a RetrieveUpdateDestroyAPIView
classe:
class TodoDetail(generics.RetrieveUpdateDestroyAPIView):
queryset = Todo.objects.all()
serializer_class = TodoSerializer
Linguagem de código: Python ( python )
A TodoDetail
turma é responsável pelas seguintes operações:
- Recuperar uma tarefa por id.
- Atualize uma tarefa existente.
- Destrua (ou exclua) uma tarefa.
Na TodoDetail
classe, também precisamos definir o queryset
and serializer_class
.
Definição de endpoints de API
A seguir definem os endpoints da API no urls.py
aplicativo api
:
from django.urls import path
from .views import TodoList, TodoDetail
urlpatterns = [
path('todos/', TodoList.as_view(), name='todo_list'),
path('todos/<int:pk>/', TodoDetail.as_view(), name='todo_detail'),
]
Linguagem de código: Python ( python )
Interagindo com a API usando a API navegável
O Django REST Framework suporta a geração de páginas HTML fáceis de usar de todos os recursos quando você solicita o formato HTML.
Essas páginas permitem navegar facilmente pelas APIs e enviar dados aos endpoints da API usando POST, PUT, PATCH e DELETE.
Obtendo todos todos
Abra o endpoint http://localhost:8000/api/v1/todos/ e você verá a página a seguir.
Ao abrir o api/v1/todos/
no navegador da web, você está executando uma solicitação GET para o endpoint. A página retorna uma lista de todos na página bem formatada em HTML.
Para obter o formato JSON bruto, você especifica o formato da solicitação GET clicando no item de menu json no botão GET conforme mostrado na imagem a seguir:
A API retornará o JSON bruto:
[{"id":1,"title":"Learn Python","completed":false,"user":"john"},{"id":2,"title":"Study Django","completed":false,"user":"john"},{"id":3,"title":"Master Django REST API","completed":false,"user":"john"}]
Linguagem de código: JSON/JSON com comentários ( json )
Se você tiver uma extensão do visualizador JSON instalada no navegador da web, poderá ver o formato JSON legível da seguinte maneira:
[
{
"id": 1,
"title": "Learn Python",
"completed": false,
"user": "john"
},
{
"id": 2,
"title": "Study Django",
"completed": false,
"user": "john"
},
{
"id": 3,
"title": "Master Django REST API",
"completed": false,
"user": "john"
}
]
Linguagem de código: JSON/JSON com comentários ( json )
Criando uma nova tarefa
Abra o ponto final /api/v1/todos/
. Mas desta vez emitiremos uma POST
solicitação em vez de GET
uma solicitação.
Primeiro, insira as informações da tarefa:
Em segundo lugar, clique no POST
botão e você obterá a seguinte resposta:
A API cria uma nova tarefa com id 4. Além disso, o usuário é aquele em que você está logado no momento.
Observe que você precisa fazer login no site de administração como um usuário, por exemplo, john, para que o método perform_create() do TodoList possa obter as informações do usuário a partir da solicitação.
Obtendo uma tarefa específica
Abra o endpoint /api/v1/todos/4/
para obter informações detalhadas sobre a tarefa com o ID 4:
Neste caso, estamos fazendo uma solicitação GET ao endpoint da API/api/v1/todos/4/
Atualizando uma tarefa
A página de atualização de uma tarefa também é aquela que obtém os detalhes de uma tarefa.
Abra o endpoint /api/v1/todos/4/
para obter os detalhes da tarefa com id 4 e role para baixo até o formulário HTML:
Segundo, modifique alguns valores do Todo
JSON e clique no botão PUT para emitir uma PUT
solicitação e você obterá a seguinte resposta:
Excluindo uma tarefa
Abra o endpoint para visualizar a tarefa com id 4: /api/v1/todos/4/
e clique no botão Excluir:
Ele solicitará a confirmação de exclusão:
Se você clicar no botão Excluir, receberá a seguinte resposta:
A API emitiu uma DELETE
solicitação ao endpoint e retornou o status HTTP 204 para indicar que a tarefa foi excluída com sucesso.
Baixe o projeto
Baixe o código-fonte do projeto aqui.
Resumo
- Use Django REST Framework para construir API RESTful rapidamente.
- As etapas para definir a API são criar uma classe serializadora (
serializers.py
), definir visualizações (views.py
) e conectar as visualizações com URLs (urls.py
). - Use a interface da API navegável para interagir com APIs.