Guia de Postman para API REST

Seja bem-vindo ao mundo das APIs REST! Neste guia vamos explorar uma Biblioteca Digital fictícia. Você vai aprender a testar endpoints como quem organiza estantes, cadastra livros e cuida dos leitores com carinho técnico.

🛠️ Instalando o Postman

Antes de tudo, precisamos da nossa ferramenta de trabalho.

1. Acesse: https://www.postman.com/downloads/
2. Baixe e instale de acordo com seu sistema operacional
3. Crie uma conta (opcional, mas facilita sincronização e organização)

🎒 Preparando o Ambiente

Criando uma nova Coleção

No Postman, coleções funcionam como pastas para seus testes.

1. Clique em "New" → "Collection"
2. Nome: API Biblioteca
3. Descrição: Testes da API REST da Biblioteca Digital
4. Clique em Create

📚 Testando os Endpoints

1. 🧾 GET - Listar Livros

GET http://localhost:8080/api/livros

Passo a passo:

1. Novo Request → Nome: Listar Livros
2. Método: GET
3. URL: http://localhost:8080/api/livros
4. Clique em Send

Resposta esperada:

[
{"id":1,"titulo":"1984","autor":"George Orwell"},
{"id":2,"titulo":"O Hobbit","autor":"J.R.R. Tolkien"}
]

2. ✍️ POST - Cadastrar Livro

POST http://localhost:8080/api/livros
Headers: Content-Type: application/json

Body (JSON):

{
"titulo": "Dom Casmurro",
"autor": "Machado de Assis",
"isbn": "978-85-01-00001-1",
"anoPublicacao": 1899,
"disponivel": true
}

Passos:

1. Novo Request → Nome: Cadastrar Livro
2. Método: POST
3. URL: http://localhost:8080/api/livros
4. Headers:

• Content-Type: application/json

1. Body → raw → JSON (insira os dados acima)
2. Clique em Send

3. 🔍 GET - Buscar Livro por ID

GET http://localhost:8080/api/livros/1

Passos:

1. Novo Request → Nome: Buscar Livro por ID
2. Método: GET
3. URL: http://localhost:8080/api/livros/1
4. Clique em Send

4. 📝 PUT - Atualizar Livro

PUT http://localhost:8080/api/livros/1
Headers: Content-Type: application/json

Body (JSON):

{
"id": 1,
"titulo": "1984 - Edição Especial",
"autor": "George Orwell",
"isbn": "978-85-01-00001-1",
"anoPublicacao": 1949,
"disponivel": true
}

Passos:

1. Novo Request → Nome: Atualizar Livro
2. Método: PUT
3. URL: http://localhost:8080/api/livros/1
4. Headers:

• Content-Type: application/json

1. Body → JSON com os dados atualizados
2. Clique em Send

5. 🗑️ DELETE - Remover Livro

DELETE http://localhost:8080/api/livros/1

Passos:

1. Novo Request → Nome: Remover Livro
2. Método: DELETE
3. URL: http://localhost:8080/api/livros/1
4. Clique em Send

👤 Entidades Extras

Leitores - POST

{
"nome": "Clara Souza",
"email": "clara@email.com",
"cpf": "123.456.789-00",
"telefone": "(11) 91234-5678"
}

Empréstimos - POST

{
"livroId": 2,
"leitorId": 1,
"dataEmprestimo": "2025-07-29",
"dataDevolucao": "2025-08-05"
}

🧠 Dicas para Navegar na API

Headers úteis:

• Content-Type: application/json
• Accept: application/json

Códigos de status (HTTP):

• 200 OK – Deu certo!
• 201 Created – Criado com sucesso
• 204 No Content – Deletado sem problemas
• 400 Bad Request – Algo no JSON está fora do esperado
• 404 Not Found – Recurso não encontrado
• 500 Internal Server Error – Erro no servidor, veja os logs

🗂️ Organizando no Postman como um(a) bibliotecário(a)

1. Crie pastas na sua Collection:

• 📁 Livros
• 📁 Leitores
• 📁 Empréstimos

1. Use variáveis de ambiente:

• Crie um Environment chamado Local
• Adicione a variável baseUrl com o valor http://localhost:8080
• Agora use nas URLs: {{baseUrl}}/api/livros

🧪 Automatizando Testes Simples

pm.test("Status 200 OK", function () {
  pm.response.to.have.status(200);
});

pm.test("Resposta não está vazia", function () {
  pm.expect(pm.response.text()).to.not.be.empty;
});

Você pode adicionar esses trechos na aba Tests de cada request.

🧯 E se algo der errado?

Erros comuns:

• ❌ 404 Not Found: URL digitada errada? ID existe?
• ❌ 400 Bad Request: JSON mal formatado
• ❌ 415 Unsupported Media Type: esqueceu o Content-Type?
• ❌ API não responde: o projeto está rodando? Verifique o console do Spring Boot

✅ Checklist rápido antes de testar:

• Aplicação Spring Boot está rodando?
• URL está correta?
• Método HTTP correto?
• Headers adicionados?
• JSON válido no corpo da requisição?

Seja você um guardião de livros ou de endpoints, este guia foi feito para facilitar seus testes e te ajudar a dominar o Postman com tranquilidade e propósito.