Tipos de Parâmetros nas requisições REST

API REST 14 de Ago de 2020

Neste post vamos explicar os conceitos dos parâmetros nas requisições de API's REST mostrando suas principais diferenças e casos de uso.

Há várias maneiras de fazer requisições HTTP do front end para o back end usando REST.

Os verbos são: Get, Put, Post, Patch, Delete sendo que alguns podem receber parâmetros na URL ou não.

Para exemplificar os tipos vamos usar os verbos GET e POST nas requisições.

Tipos

Existem três tipos de parâmetros, dois deles comumente utilizados no método GET e um no método no POST.

Query Params (GET)
Route Params (GET)
Body Params (POST e PUT)

Query & Route Params

✅ Query params

Recebe os dados da requisição como parâmetro na URL.

Caso de uso: Filtros para fazer consultas na aplicação.

Pode conter um ou mais parâmetros:

Exemplos:

http://minhaapi.com/banks?name=nubank

No exemplo acima acesso o recurso (ou rota) banks, filtrando por name. Para inserir parâmetros coloco ? após a rota e adiciono a propriedade e valor: name=nubank.

http://minhaapi.com/movies?name=transformers&actors=megan,peter

No exemplo acima acesso API de filmes, pesquisando por name e actors. Sempre que for passar mais de um parâmetro podemos colocar & para separar os parâmetros.

✅ Route params

Recebe os dados da requisição na rota.

Caso de uso: Melhor maneira para buscar algo específico, deletar ou atualizar usando o identificador único, por exemplo:

GET: https://api.github.com/users/tgmarinho
PUT: https://api.github.com/users/tgmarinho
DELETE: https://api.github.com/users/380327

Nesse exemplo acima busco, atualizo e deleto o usuário do GitHub com login: tgmarinho ou id: 380327.

As duas maneiras mudam a forma de escrever o código, veja:

/**
* Query params = ?name=Thiago
* Route params = /users/1
*/

// Query params: ?name=thiago

// faça a requisição no navegador: http://localhost:3333/users/?name=Thiago
server.get("/users", (req, res) => {
 const name = req.query.name;	
 return res.json({ message: `Hello ${name}` });
});

// Route Params = /users/1

// faça a requisição no navegador: http://localhost:3333/users/1
server.get("/users/:id", (req, res) => {
 // const id = req.params.id; 
 const { id } = req.params; // desestruturado com ES06	
 return res.json({ message: `Buscando o usuário de ID: ${id}`});
});

✅ Body Params

Recebe os dados da requisição no corpo da requisição, em um objeto em JSON. Sempre utilizando no método POST da requisição.

{ 
	"name": "Thiago", "age": 18, "email": "thiago@mail.com"
}

No Controller você pega a requisição para salvar os dados no banco de dados.

server.post("/users", (req, res){ 
 const { name, age, email } = req.body; 
 await connection("users").insert({ name, age, email }); 
return res.json({ id }); }

Um adendo

Embora o objetivo não seja explicar as diferenças entre os métodos HTTP, preciso explicar uma diferença que será visto na prática no mercado:

O método PUT também recebe Route Params informando qual recurso vai ser modificado e recebe o Body Params com os valores que serão alterados. A diferença básica, em poucas palavras, o método POST cria um novo recurso e o PUT altera um recurso existente, por isso ele recebe um Route Params primeiro para localizar o recurso no back end e altera-o com os dados enviados via Body Params.