Sumário

• BandKamp API
• Iniciando a aplicação
• Rodando o projeto
• Endpoints
  Rotas sem autenticação
  • POST /api/users/
  • POST /api/login/
  • GET /api/albums/
  • GET /api/albums/
  • GET /api/albums/<int: album_id>/songs/
  
  Rotas com autenticação
  • GET /api/users/<int: user_id>
  • PATCH /api/users/<int: user_id>
  • DELETE /api/users/<int: user_id>
  • POST /api/albums/
  • POST /api/albums/<int: album_id>/songs/


• Utilizando o Django Admin Site

BandKamp-API

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
• is_superuser: Booleano

Retorno:

• status 201: 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": "igor",
	"email": "igor@mail.com",
	"password": "2313",
	"first_name": "Igor",
	"last_name": "Torres"
}

O campo is_superuser, é opcional. Caso não seja enviado, o valor padrão será false.

Exemplo de resposta:

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

{
	"id": 1,
	"username": "igor",
	"email": "igor@mail.com",
	"first_name": "Igor",
	"last_name": "Torres",
	"is_superuser": false
}

POST /api/login/

Retorna um token de acesso para o usuário.

Parâmetros de requisição:

• username
• password

Retorno:

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

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

{
  "username": "igorttdp",
  "password": "2313"
}

Exemplo de resposta:

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

{
	"refresh": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbl90eXBlIjoicmVmcmVzaCIsImV4cCI6MTY4MjA4Mjk3MCwiaWF0IjoxNjgxNDc4MTcwLCJqdGkiOiI4Zjc5MmFhNDM1ZGU0YmQyYTA5ZjViY2ExYzBhOWFiYiIsInVzZXJfaWQiOjR9.1nPD0MqD5BDwUrwnZdiXY305v1mvxtgAbeGKNeroSqE",
	"access": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbl90eXBlIjoiYWNjZXNzIiwiZXhwIjoxNjgxNTMyMTcwLCJpYXQiOjE2ODE0NzgxNzAsImp0aSI6IjljMzUxNzkzZmNmZjRmOTRhYTZmMTg1MjYzZjdkYzRkIiwidXNlcl9pZCI6NH0.KzttEdSXI6-4Gb2SVQly25JYMQ_pZyjyo1rH655bm8U"
}

GET /api/albums/

Retorna todos os álbums cadastrados na aplicação.

Parâmetros de requisição:

• Nenhum Parâmetro

Retorno:

• status 200: Albúms retornados com sucesso

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

{
	"count": 2,
	"next": null,
	"previous": null,
	"results": [
		{
			"id": 1,
			"name": "Appetite for Destruction",
			"year": 1987,
			"user_id": 2
		},
		{
			"id": 2,
			"name": "Back in Black",
			"year": 1980,
			"user_id": 2
		}
	]
}

GET /api/albums/<int: album_id>/songs/

Retorna todas as músicas pertencentes a um álbum.

Parâmetros de consulta:

• album_id. Exemplo: /api/albums/1/songs/

Parâmetros de requisição:

• Nenhum Parâmetro

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

{
	"count": 6,
	"next": "http://localhost:8000/api/albums/1/songs/?page=2",
	"previous": null,
	"results": [
		{
			"id": 3,
			"title": "Sweet Child O' Mine",
			"duration": "05:03",
			"album_id": 1
		},
		{
			"id": 4,
			"title": "My Michelle",
			"duration": "03:40",
			"album_id": 1
		},
		{
			"id": 5,
			"title": "Welcome to the Jungle",
			"duration": "04:33",
			"album_id": 1
		},
		{
			"id": 6,
			"title": "It's So Easy",
			"duration": "03:23",
			"album_id": 1
		},
		{
			"id": 7,
			"title": "Anything Goes",
			"duration": "03:23",
			"album_id": 1
		}
	]
}

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 "/login".

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

"Authorization": {
    "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbl90eXBlIjoiYWNjZXNzIiwiZXhwIjoxNjgxNTMyMTcwLCJpYXQiOjE2ODE0NzgxNzAsImp0aSI6IjljMzUxNzkzZmNmZjRmOTRhYTZmMTg1MjYzZjdkYzRkIiwidXNlcl9pZCI6NH0.KzttEdSXI6-4Gb2SVQly25JYMQ_pZyjyo1rH655bm8U"
}

GET /api/users/<int: user_id>

Retorna os dados do próprio usuário. Caso passe um usuário diferente do que está armazenado no token, um erro será retornado.

Parâmetros de consulta:

• user_id. Exemplo: /api/users/1

Parâmetros de requisição:

• Nenhum Parâmetro

Retorno:

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

Exemplo de resposta:

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

{
	"refresh": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbl90eXBlIjoicmVmcmVzaCIsImV4cCI6MTY4MjA4NzA2NCwiaWF0IjoxNjgxNDgyMjY0LCJqdGkiOiI2NGQ4ZDZiZmRiYzY0OWJlYjJkMGJhYzI5NjU2N2Q2ZSIsInVzZXJfaWQiOjJ9.94IWvi-fTCtRzWdjqB2dXxve9wOM15DbZEFJ8adVhKE",
	"access": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbl90eXBlIjoiYWNjZXNzIiwiZXhwIjoxNjgxNTM2MjY0LCJpYXQiOjE2ODE0ODIyNjQsImp0aSI6IjM2ODkzZmI4ZTI3NjQxOTA4NWNmOTc5MjY5YjIxYmVkIiwidXNlcl9pZCI6Mn0.fDwIsezwyee6mKvwZAdvSUqzexS4Vv9ii2RyDz4SU00"
}

PATCH /api/users/<int: user_id>

Atualiza os dados do próprio usuário

Parâmetros de requisição:

• username: Opcional
• email: Opcional
• password: Opcional
• first_name: Opcional
• last_name: Opcional

Retorno:

• status 200: Novo usuário criado com sucesso
• status 400: Dados não passaram pela validação
• status 401: Token invalido / não enviado
• status 403: Token não tem permissão

Exemplo de requisição:

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

{
	"username": "igorttdp",
	"email": "igorttdp@mail.com"
}

Exemplo de resposta:

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

{
	"id": 1,
	"username": "igorttdp",
	"email": "igorttdp@mail.com",
	"first_name": "Igor",
	"last_name": "Torres",
	"is_superuser": false
}

DELETE /api/users/<int: user_id>

Deleta o próprio usuário.

Parâmetros de requisição:

• Nenhum Parâmetro

Retorno:

• status 204: Usuário deletado com sucesso!
• status 401: Token invalido / não enviado
• status 403: Token não tem permissão

DELETE api/users/1 HTTP/1.1
Content-Type: application/json

No content

POST /api/albums/

Cria um novo álbum.

Parâmetros de requisição:

• name: String
• year: Integer

Exemplo de requisição:

POST api/albums/1 HTTP/1.1
Content-Type: application/json

{
	"name": "Appetite for Destruction",
	"year": 1987
}

Exemplo de resposta:

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

{
    "id": 1,
    "name": "Appetite for Destruction",
    "year": 1987,
    "user_id": 1
},

POST /api/albums/<int: album_id>/songs/

Adiciona uma nova música a um álbum existente.

Parâmetros de consulta:

• album_id. Exemplo: /api/albums/1/songs/

Parâmetros de requisição:

• Title: String
• Duration: String

Retorno:

• status 201: Música adicionada com sucesso!
• status 401: Token invalido / não enviado
• status 403: Token não tem permissão

Exemplo de requisição:

POST api/albums/1/songs/ HTTP/1.1
Content-Type: application/json

{
	"title": "Sweet Child O' Mine",
	"duration": "05:03"
}

Exemplo de resposta:

POST api/albums/1/songs/ HTTP/1.1
Content-Type: application/json

{
	"id": 1,
	"title": "Sweet Child O' Mine",
	"duration": "05:03",
	"album_id": 1
}

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!