Estrutura REST do Django – Acervo Lima Tutorials

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 djangorestframeworkLinguagem de código:  texto simples  ( texto simples )

Segundo, atualize o requirements.txtarquivo:

pip freeze > requirements.txtLinguagem de código:  texto simples  ( texto simples )

Terceiro, registre rest_frameworko aplicativo no settings.pyprojeto:

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 apino diretório do projeto para hospedar o código da API:

mkdir apiLinguagem de código:  texto simples  ( texto simples )

Segundo, crie três arquivos Python dentro do apidiretó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 apino INSTALLED_APPSarquivo settings.pydo 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 TodoSerializerno serializers.pyarquivo que serializa a Todoinstâ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 serializersmódulo do rest_frameworkpacote:

from rest_framework import serializersLinguagem de código:  Python  ( python )

Segundo, importe o Todomodelo do modelsmódulo do todoaplicativo:

from todo.models import TodoLinguagem de código:  Python  ( python )

Terceiro, defina a TodoSerializerclasse que estende a serializers.ModelSerializerclasse:

class TodoSerializer(serializers.ModelSerializer):
    ...Linguagem de código:  Python  ( python )

Fornece ModelSerializeruma maneira rápida de definir uma classe serializadora com campos correspondentes aos campos do modelo.

Dentro da TodoSerializerclasse, defina uma Metaclasse que inicialize:

model– especifica o Todomodelo.
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 Todomodelo está associado ao Usermodelo, especificamos o useratributo como StringRelatedField()e definimos seu parâmetro como read_only.

Isso significa que the Todoterá a representação em string do Userwhich é the usernameneste caso.

O read_onlyparâmetro permite que o serializador leia apenas o Usermodelo. Em outras palavras, o serializador não poderá atualizar o Usermodelo.

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 shellLinguagem de código:  CSS  ( css )

Segundo, importe o Todomodelo e TodoSerializera classe:

>>> from api.serializers import TodoSerializer
>>> from todo.models import TodoLinguagem de código:  JavaScript  ( javascript )

Terceiro, obtenha o Todocom 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 TodoSerializermodelo Todoe 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 TodoSerialzierobjeto 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.pyarquivo:

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 genericsdo rest_framework:

from rest_framework import genericsLinguagem de código:  Python  ( python )

Eles genericsfornecem várias classes de visualização base, como ListCreateAPIViewe RetrieveUpdateDestroyAPIView.

Em segundo lugar, importe o TodoSerializerdo serializersaplicativo apie Todoo modelo do modelsaplicativo todo:

from .serializers import TodoSerializer
from todo.models import TodoLinguagem de código:  Python  ( python )

Terceiro, defina a TodoListclasse que estende a ListCreateAPIViewclasse. A TodoListturma é 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 TodoListclasse, especifique o querysetusado para retornar todos todos e serializer_classusado para serialização/desserialização das Todoinstâncias.

O perform_create()método da classe TodoSerializer é invocado automaticamente quando você salva uma nova instância Todo.

Como cada Todoinstância precisa de uma Userinstância, atribuímos o valor userda solicitação HTTP ( request) ao useratributo da Todoinstância antes de salvá-la no banco de dados.

Finalmente, defina a TodoDetailclasse que estende a RetrieveUpdateDestroyAPIViewclasse:

class TodoDetail(generics.RetrieveUpdateDestroyAPIView):
    queryset = Todo.objects.all()
    serializer_class = TodoSerializerLinguagem de código:  Python  ( python )

A TodoDetailturma é responsável pelas seguintes operações:

Recuperar uma tarefa por id.
Atualize uma tarefa existente.
Destrua (ou exclua) uma tarefa.

Na TodoDetailclasse, também precisamos definir o querysetand serializer_class.

Definição de endpoints de API

A seguir definem os endpoints da API no urls.pyaplicativo 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 POSTsolicitação em vez de GETuma solicitação.

Primeiro, insira as informações da tarefa:

Em segundo lugar, clique no POSTbotã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 TodoJSON e clique no botão PUT para emitir uma PUTsolicitaçã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 DELETEsolicitaçã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.

API REST do Django

Permissões da estrutura REST do Django