Sumário

• KMDB-API
• Iniciando a aplicação
• Rodando o projeto
• Endpoints
  • POST /api/users/
  • POST /api/#/
  • GET /api/users/
  • Criando usuário ADMIN via CLI
    • Admin Padrão
    • Admin Personalizado
    • Possíveis Erros
  • GET /api/movies/
  • POST /api/movies/
• Utilizando o Django Admin Site

KMDB-API

Uma API para gerenciamento de filmes e reviews.

Iniciando a aplicação

Primeiro, é necessário criar um ambiente virtual para poder instalar os pacotes. Pode ser feito da seguinte forma no terminal aberto no diretório do projeto:

python -m venv venv

Obs: o segundo "venv" é o nome da pasta que deseja criar para a instalação dos pacotes, porém por boas práticas aconselhamos manter dessa forma!

Uma vez que a pasta já foi criada, basta rodar o seguinte comando para entrar o ambiente virtual

• Linux

source venv/bin/activate

• Windows

Comando para verificação de entrada no ambiente virtual:

Get-ExecutionPolicy

Caso o retorno seja "Restricted", basta inserir o seguinte código:

Set-ExecutionPolicy AllSigned

Digite "S" ou "Y" para confirmar

Após esse processo, basta inserir o seguinte comando:

.\venv\Scripts\activate

Obs: caso esteja utilizando o bash do Git, o comando para ativar o ambiente virtual é o seguinte:

source venv/Scripts/activate

Agora que o ambiente virtual está criado e já entramos nele, basta rodar o seguinte comando para instalar as dependências:

pip intall -r requirements.txt

Rodando o projeto

Uma vez que as dependências do projeto foram instaladas de forma correta, para rodar o projeto localmente basta rodar o seguinte comando:

python manage.py runserver

Endpoints

POST /api/users/

Cria um novo usuário

Parâmetros de requisição:

• username: String
• email: String
• password: String
• first_name: String
• last_name: String
• bio: Campo de texto
• is_critic: Booleano

Retorno:

• status 200: Novo usuário criado com sucesso
• status 400: Dados não passaram pela validação

Exemplo de requisição:

POST api/users/ HTTP/1.1
Content-Type: application/json

{
    "username": "Igorttdp",
    "email": "igor@mail.com",
    "passoword": "123456",
    "first_name": "Igor",
    "last_name": "Torres",
    "bio": "Oi, meu nome é Igor :D",
    "is_critic": true
}

O campo is_critic, caso true, referencia esse usuário como sendo um crítico de filmes. Um usuário crítico pode criar e publicar reviews dos filmes presentes no banco de dados da aplicação.

Exemplo de resposta:

HTTP 201 Created
Allow: GET, POST, HEAD, OPTIONS
Content-Type: application/json
Vary: Accept

{
    "id": "08a1f9f0-c0fd-435b-975f-0035b3749a8b",
    "username": "Igorttdp",
    "email": "igor@mail.com",
    "first_name": "Igor",
    "last_name": "Torres",
    "bio": "Sou o Igor :D",
    "is_critic": true,
    "is_superuser": false,
    "updated_at": "2023-04-13T20:20:38.765563Z"
}

POST /api/#/

Retorna um token de acesso para o usuário.

Parâmetros de requisição:

• email
• password

Retorno:

• status 200: Usuário autenticado com sucesso
• status 400: Dados não passaram pela validação
• status 401: Dados incorretos

POST /# HTTP/1.1
Content-Type: application/json

{
  "email": "igor@mail.com",
  "password": "123456"
}

Exemplo de resposta:

HTTP 200 OK
Allow: POST, OPTIONS
Content-Type: application/json
Vary: Accept

{
    "refresh": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbl90eXBlIjoicmVmcmVzaCIsImV4cCI6MTY4MjAyMjc3NSwiaWF0IjoxNjgxNDE3OTc1LCJqdGkiOiJmNjEzYzYxMjlkMjg0YTgzYTNlOTgyZTY5ODAxY2M2MiIsInVzZXJfaWQiOiIwOGExZjlmMC1jMGZkLTQzNWItOTc1Zi0wMDM1YjM3NDlhOGIifQ.d3Qi4GPcr1xeSIS2kQDfwaivYm3KSpR6clu5K9vQr78",
    "access": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbl90eXBlIjoiYWNjZXNzIiwiZXhwIjoxNjgxNTA0Mzc1LCJpYXQiOjE2ODE0MTc5NzUsImp0aSI6ImVlMGVmYTlhN2UzYjQ0ZmE4Yjk2ZTliZTJjNGE4Zjk2IiwidXNlcl9pZCI6IjA4YTFmOWYwLWMwZmQtNDM1Yi05NzVmLTAwMzViMzc0OWE4YiJ9.jmHLaBVYArfqoMLwbX10DiaElJPvF0B6_8qhhqglZ_8"
}

Rotas com autenticação

Todas as rotas abaixo necessitam de autenticação. Deve ser configurada na requisição utilizando o token "access" de resposta em "/#".

Inclua o token JWT em todas as requisições subsequentes no header Authorization utilizando o prefixo Bearer, como no exemplo abaixo:

"Authorization": {
    "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbl90eXBlIjoiYWNjZXNzIiwiZXhwIjoxNjgxNTA0Mzc1LCJpYXQiOjE2ODE0MTc5NzUsImp0aSI6ImVlMGVmYTlhN2UzYjQ0ZmE4Yjk2ZTliZTJjNGE4Zjk2IiwidXNlcl9pZCI6IjA4YTFmOWYwLWMwZmQtNDM1Yi05NzVmLTAwMzViMzc0OWE4YiJ9.jmHLaBVYArfqoMLwbX10DiaElJPvF0B6_8qhhqglZ_8"
}

GET /api/users/

Retorna todos os usuários registrados no banco de dados desde que o token tenha permissão de Administrador.

Só é possível criar um usuário administrador (super-usuário) por meio de um comando via CLI chamado "create_admin". Veja abaixo um exemplo

Criação de usuário admin via CLI

Admin Padrão

Exemplo:

python manage.py create_admin

Resposta:

Admin `admin` successfully created!

Nota: Os dados para logar são:
username: admin
password: admin1234

Admin Personalizado

python manage.py create_admin --name Igor --email igor@mail.com --password senha1234

Resposta:

Admin `Igor` successfully created!

Nota: Os atributos "--name", "--email" e "--password" são opcionais e se não forem passados, utilizarão os valores pré-definidos "name = Admin", "password = Admin1234" e "email = admin@mail.com >

Aviso

Se o comando for enviado com dados repetidos, ele poderá retornar os seguintes erros:

Username `Admin` already taken.

#ou

Email `admin@mail.com` already taken.

Exemplo de resposta:

HTTP 200 OK
Allow: POST, OPTIONS
Content-Type: application/json
Vary: Accept

{
	"count": 3,
	"next": null,
	"previous": null,
	"results": [
		{
			"id": "209a1f71-6bed-422d-9448-1e57bab9c036",
			"username": "admin",
			"email": "admin@example.com",
			"first_name": "Admin",
			"last_name": "Adm",
			"bio": "Eu sou o admin",
			"is_critic": false,
			"is_superuser": true,
			"updated_at": "2023-04-13T20:41:20.786993Z"
		},
		{
			"id": "08a1f9f0-c0fd-435b-975f-0035b3749a8b",
			"username": "Igorttdp",
			"email": "igor@mail.com",
			"first_name": "Igor",
			"last_name": "Torres",
			"bio": "Sou o Igor :D",
			"is_critic": true,
			"is_superuser": false,
			"updated_at": "2023-04-13T20:20:38.765563Z"
		},
		{
			"id": "f9c08819-b9c1-457b-a8f3-0909225f0886",
			"username": "Rafael",
			"email": "",
			"first_name": "Rafael",
			"last_name": "Teixeira",
			"bio": "Olá, eu sou o Rafa!",
			"is_critic": false,
			"is_superuser": false,
			"updated_at": "2023-04-13T20:41:48.498022Z"
		}
	]
}

GET /api/movies/

Retorna uma lista contendo todos os filmes.

Exmplo de Resposta:

HTTP 200 OK
Allow: GET, POST, HEAD, OPTIONS
Content-Type: application/json
Vary: Accept

{
    "count": 2,
    "next": null,
    "previous": null,
    "results": [
        {
            "id": "ee535837-83ce-4c72-bf85-16abcd99d97d",
            "genres": [
                {
                    "id": "e1589ff5-e015-4161-aacd-b665cb3153a3",
                    "name": "Action"
                },
                {
                    "id": "919d0ddb-0709-4e18-83e0-d7d204257fed",
                    "name": "Drama"
                }
            ],
            "title": "Jonh Wick 4",
            "duration": "03:00:00",
            "premiere": "2023-04-30",
            "budget": "20.00",
            "overview": "Jonh wick é um filme muito loko que no fim, depois de tomar tanto tiro ele se cansou e morreu. F"
        },
        {
            "id": "acbffdba-7630-4c26-8206-239a0b73530d",
            "genres": [
                {
                    "id": "e1589ff5-e015-4161-aacd-b665cb3153a3",
                    "name": "Action"
                },
                {
                    "id": "382479e4-bdf7-4b20-9d4d-7edc88b923d5",
                    "name": "Adventure"
                }
            ],
            "title": "Super Mario Bros. O Filme",
            "duration": "01:32:00",
            "premiere": "2023-04-13",
            "budget": "25.00",
            "overview": "Mario é um encanador junto com seu irmão Luigi. Um dia, eles vão parar no reino dos cogumelos, governado pela Princesa Peach, mas ameaçado pelo rei dos Koopas, que faz de tudo para conseguir reinar em todos os lugares."
        }
    ]
}

POST /api/movies/

Cria um novo filme.

Exemplo de requisição:

POST api/movies/ HTTP/1.1
Content-Type: application/json

{
    "title": "Jonh Wick 4",
    "duration": "03:00:00",
    "premiere": "2023-04-30",
    "budget": 20.00,
    "overview": "Com o preço por sua cabeça cada vez maior, o lendário assassino de aluguel John Wick leva sua luta contra o High Table global enquanto procura os jogadores mais poderosos do submundo, de Nova York a Paris, do Japão a Berlim.",
    "genres": ["Action", "Drama"],
}

O campo genres deve ser uma lista de gêneros. Estes podem ser existentes ou não no banco de dados. Se o gênero não for existente, então ele será criado, caso contrário o gênero existente será referenciado no objeto de Movie.

Exemplo de resposta:

{
  "id": "ee535837-83ce-4c72-bf85-16abcd99d97d",
  "genres": [
    {
      "id": "e1589ff5-e015-4161-aacd-b665cb3153a3",
      "name": "Action"
    },
    {
      "id": "919d0ddb-0709-4e18-83e0-d7d204257fed",
      "name": "Drama"
    }
  ],
  "title": "Jonh Wick 4",
  "duration": "03:00:00",
  "premiere": "2023-04-30",
  "budget": "20.00",
  "overview": "Com o preço por sua cabeça cada vez maior, o lendário assassino de aluguel John Wick leva sua luta contra o High Table global enquanto procura os jogadores mais poderosos do submundo, de Nova York a Paris, do Japão a Berlim."
}

Utilizando o Django Admin Site

Django Admin Site é uma interface no frontend projetada para facilitar o gerenciamento de inserção e remoção de dados. Você pode utiliza-lá se tiver acesso de administrador.

Para acessar, basta colocar as informações do usuário administrador e clicar em "Log In". Caso ainda não tenha criado um usuário admin, clique aqui: Criação de usuário admin via CLI.

Aqui você tem acesso a todas as tabelas do banco de dados, assim como acesso a ações de criação e remoção de todos os dados!