ASP.NET Core -  Recebendo parâmetros

 Neste artigo veremos 4 formas básicas de receber parâmetros em uma API.

De forma bem simples, podemos receber parâmetros em uma ASP .NET Core WEB API usando: query strings, informando os parâmetros no path, usando o body do request e usando o cabeçalho do request.

1- Passando parâmetros via Query String

Vamos supor que você tenha duas chaves de string de consulta: nome e idade.

Para adicionar esses parâmetros via query string ou string de consulta, basta adicionar os parâmetros de método com nomes que correspondam aos nomes de chave de string de consulta (nome e servico):

Assim em um projeto com um controlador TesteController onde temos a entidade Cliente:

public class Cliente
{
    public Guid Id { get; set; }
    public string? Nome { get; set; }   
    public int Idade { get; set; }   
}

Podemos definir o método Get contendo os nomes e tipos das chaves que desejamos enviar como parãmetro:

[Route("api/[controller]")]
[ApiController]
public class TesteController : ControllerBase
{
    [HttpGet()]
    public Cliente Get(string nome, int idade)
    {
        return new Cliente()
        {
            Id = Guid.NewGuid(),
            Nome = nome,
            Idade = idade
        };
    }
}

Agora para passar os parâmetro via query string basta digitarmos no navegador:

https://localhost/api/teste?nome=Maria&idade=23

Os valores da string de consulta são mapeados para os parâmetros do método (nome, idade) e retorna a seguinte resposta 200 (OK):

Usando a interface do Swagger basta informar os valores dos parâmetros na interface:

Exibindo a seguinte resposta:

Usando parâmetros em rotas

Para adicionar parâmetros de caminho, configure a rota (no atributo HttpGet) com os nomes dos parâmetros e, em seguida, adicione os parâmetros de método com nomes correspondentes:

    [HttpGet("{nome}/{idade}")]
    public Cliente Get2(string nome, int idade)
    {
        return new Cliente()
        {
            Id = Guid.NewGuid(),
            Nome = nome,
            Idade = idade
        };
    } 

A seguir basta enviar um request com os valores dos parâmetros como parte do caminho :

https://localhost:7278/api/teste/paulo/33

Acima temos o resultado obtido.

Usando o Body do Request

Quando você tem vários parâmetros, é comum encapsulá-los em um tipo complexo e obtê-los do corpo do Request.

Para fazer isso, adicione o tipo complexo como um parâmetro de método:

    [HttpPost()]
    public IActionResult Post(Cliente cliente)
    {
        return Ok($"Postado {cliente.Nome}");
    }

A seguir basta enviar o request com o JSON no body. Usando o Postman podemos fazer assim:

Nota: Para instalar o Postman acesse esse link : https://www.getpostman.com/apps ou abra o Google Chrome e digite postam e a seguir clique no link:  Postman - Chrome Web Store

O JSON do body do request é desserializado e mapeado para o parâmetro Cliente retornando uma resposta 200 (OK) e o o texto Postado Macoratti.

Usando Header do request

Às vezes é útil enviar parâmetros por meio de cabeçalhos do request. Estes são frequentemente usados em adição a outros parâmetros.

Para adicionar um parâmetro de cabeçalho do request, basta adicionar um parâmetro de método com o mesmo nome do cabeçalho e aplicar o atributo [FromHeader] a ele.

Para mostrar isso vamos incluir na entidade Cliente a propriedade ImagemUrl:

public class Cliente
{
    public Guid Id { get; set; }
    public string? Nome { get; set; }   
    public int Idade { get; set; }  
    public string ImagemUrl { get; set; }
}

Estamos definindo o Id usando o struct Guid.

O struct Guid representa um identificador único global: um valor de 16 bytes que se gerado randomicamente irá gerar um identificador (quase) único.

A seguir vamos incluir no controlador TesteController o endpoint a seguir:

    [HttpGet("{nome}/{idade}")]
  public Cliente Get3(string nome, int idade, 
                        [FromHeader] bool incluirImagem)
  {
        string imagemUrl = null;
        if (incluirImagem)
            imagemUrl = $"{nome}.png";
        return new Cliente()
        {
            Id = Guid.NewGuid(),
            Nome = nome,
            Idade = idade,
            ImagemUrl = imagemUrl
        };
    }

Usando o método NewGuid() geramos de forma automática um identificador único atribuindo ao Id.

A seguir podemos usar o Postman e montar o seguinte request:

Observe que informamos  : GET https://localhost:7278/api/teste/Amanda/33

E informamos no Header o valor :  incluirImagem True

Podemos também usar a interface do Swagger informando os valores :

Segue o código completo do controlador TesteController:

using Api_CSV.Models;
using Microsoft.AspNetCore.Mvc;
namespace Api_CSV.Controllers;
[Route("api/[controller]")]
[ApiController]
public class TesteController : ControllerBase
{
    [HttpGet()]
    public Cliente Get(string nome, int idade)
    {
        return new Cliente()
        { 
            Id = Guid.NewGuid(),
            Nome = nome,
            Idade = idade
        };
    }
    //[HttpGet("{nome}/{idade}")]
    //public Cliente Get2(string nome, int idade)
    //{
    //    return new Cliente()
    //    {
    //        Id = Guid.NewGuid(),
    //        Nome = nome,
    //        Idade = idade
    //    };
    //}
    [HttpGet("{nome}/{idade}")]
    public Cliente Get3(string nome, int idade,
                     [FromHeader] bool incluirImagem)
    {
        string imagemUrl = null;
        if (incluirImagem)
            imagemUrl = $"{nome}.png";
        return new Cliente()
        {
            Id = Guid.NewGuid(),
            Nome = nome,
            Idade = idade,
            ImagemUrl = imagemUrl
        };
    }

    [HttpPost()]
    public IActionResult Post(Cliente cliente)
    {
        return Ok($"Postado {cliente.Nome}");
    }
}

E estamos conversados...

"Já estou crucificado com Cristo; e vivo, não mais eu, mas Cristo vive em mim; e a vida que agora vivo na carne, vivo-a pela fé do Filho de Deus, o qual me amou, e se entregou a si mesmo por mim"
Gálatas 2:20

Referências:

José Carlos Macoratti