Skip to main content

Conceitos principais da API

Status: Finalizado ✅

A API feita para o Obraplay utiliza Django REST Framework

Autenticação​

O sistema possui dois tipos de autenticação, por token e por sessão. Temos vários pacotes, como por exemplo o Djoser.

Token​

A autenticação por token será feita utilizando o método POST na rota 'api/auth-token/' passando os parâmetros "username" e "password" no header da requisição. Nesse método a autenticação não tem tempo determinado para espiração.
Exemplo de JSON retornado pela API:

{"token":"99e3d92e9ece03d39970041e72fada49edbc17a6"}

Para saber mais: https://www.django-rest-framework.org/api-guide/authentication/#tokenauthentication

Sessão​

Já autenticação por sessão tem um tempo definido para espiração.
Para fazer o login por esse método é utilizado a página '/accounts/login' e acessando pela página com usuário e senha.

Para saber mais: https://www.django-rest-framework.org/api-guide/authentication/#sessionauthentication

Autorizações/Permissões​

O sistema tem 3 tipos de perfis de usuário.

Serializers​

Os serializers são uma camada para conversão. Ele traduz os dados de objetos complexos para um formato mais amigável para o cliente, como JSON e XML, mas também converte vice-versa.
Os arquivos de serializer estão na pasta api de cada APP Django. Nele são inseridos regras como:

  • Quais campos aquela rota irá aceitar
  • Caso seja uma requisição GET, qual a profundidade de dados do JSON

Para saber mais: https://www.django-rest-framework.org/api-guide/serializers/#modelserializer

Models​

Modelos são representações de dados que são usados por vários lugares do sistema. Um dos utilitários que mais usa os models é o utilitário migrate onde cria/atualiza as tabelas no banco de dados. Esses models são definidos no arquivo models.py de cada APP Django.

Para saber mais: https://docs.djangoproject.com/en/4.0/topics/db/models/

Parsers​

Parsers são usados para definir para qual tipo de dado Python o conteúdo da requisição será representado dependendo do valor da propriedade HTTP Content-Type.
Na API do Obra Play não será utilizado XML.

Pagination​

As paginações são um mecanismo para selecionar apenas uma sequência de itens de uma lista. Exitem alguns tipos de paginações, entre elas: PageNumberPagination, LimitOffsetPagination, CursorPagination e Custom pagination styles

PageNumberPagination​

Esse tipo de paginação permite que seja mandado o número da página que deseja visualizar. Para requisitar uma página em específico, basta passar pela QueryString o parâmetro 'page' com o número da página. Na resposta da requisição conterá o total de registros, a lista de registros da página requisitada e as URLs para a página anterior e a posterior.

Exemplo de requisição: https://obraplay.com/api/quotations/?page=3.

Exemplo de retorno:

{
    "count": 1023,
    "next": "https://obraplay.com/api/quotations/?page=3",
    "previous": "https://obraplay.com/api/quotations/?page=5",
    "results": [
       …
    ]
}

Para saber mais: https://www.django-rest-framework.org/api-guide/pagination/#pagenumberpagination

LimitOffsetPagination​

O LimitOffsetPagination trabalha com quantidade de registros que serão retornados e a partir de qual registro será pego essa quantidade de registros. Nessa configuração serão passados os parâmetros 'limit' para a quantidade de registros e 'offset' para o início dos registros.

Exemplo de requisição: https://obraplay.com/api/quotations/?limit=100&offset=400.

Exemplo de retorno:

{
    "count": 1023,
    "next": "https://obraplay.com/api/quotations/?limit=100&offset=500",
    "previous": "https://obraplay.com/api/quotations/?limit=100&offset=300",
    "results": [
       …
    ]
}

Para saber mais: https://www.django-rest-framework.org/api-guide/pagination/#limitoffsetpagination

Filters​

Os principais tipos de filtros usados são os aplicados por usuário, por URL e os por parâmetros de query string.

Para saber mais: https://www.django-rest-framework.org/api-guide/filtering/

Aplicados por usuário​

Esses filtros são aplicados a fim de retornar apenas os registros que são relacionados ao usuário logado. Não é um filtro parâmetrizavel.

Aplicados por URL​

Os aplicados por URL filtram o conjunto de registros por parte da URL.
Por exemplo na URL http://exemplo.com/api/items/coca-cola/, será filtrado pelo item coca-cola.

Aplicados por query string​

Esse tipo de filtro é o mais utilizado. É passado a coluna que deseja filtrar e por qual valor.
Por exemplo na URL http://exemplo.com/api/items/item=coca-cola&type=2, será filtrado pelo item coca-cola do tipo 2.

Sorting​

As requisições por listas podem ser feitas informando por qual coluna deve ser ordenado. Para isso é necessário adicionar a variável 'ordering' informando por qual propriedade deve ser ordenado.

Exemplo: http://obraplay.com/api/users?ordering=username

Caso deseje que a ordenação seja em ordem decresente, insira '-' no começo do nome da propriedade:
http://obraplay.com/api/users?ordering=-username

Para multiplas ordenações, insira as colunas separando-as por virgula:
http://obraplay.com/api/users?ordering=firstname,lastname

Para saber mais: https://www.django-rest-framework.org/api-guide/filtering/#orderingfilter

Mais informações​