Consumindo APIs HTTP com RestSharp

Neste artigo eu vou falar sobre o RestSharp, uma biblioteca popular que oferece funcionalidades de cliente HTTP.

Consumir APIs a partir de código C# é uma tarefa bem comum. A maneira mais comum para esse tipo de tarefa é de utilizar diretamente a classe HttpClient, mas existem algumas bibliotecas que simplificam a sua configuração e uso, como o RestSharp e o Flurl, e é dessa primeira que trato aqui. Também já escrevi um artigo sobre o Flurl, que você pode ler aqui.

Sobre o RestSharp

O RestSharp é a biblioteca de cliente Http mais popular para .NET, tendo grande capacidade de serialização/deserialização, entre outras funcionalidades.

Você pode instalar o RestSharp através do Gerenciador de pacotes NuGet ou pela .NET CLI, pode encontrar ambos comandos respectivamente abaixo.

Install-Package RestSharp -Version 3.2.0
dotnet add package RestSharp

Principais Classes e Métodos

As duas principais classes do RestSharp são:

  • RestClient: define a URL base e onde a partir dela dá para adicionar opções como autenticação, cabeçalhos, serializador, cookies, etc.
  • RestRequest: define as propriedades da requisição a ser feita, como recurso a ser acessado, método HTTP, parâmetros, etc.

Alguns métodos e propriedades da classe RestClient que são comumente utilizados:

  • AddDefaultHeader: adiciona um cabeçalho padrão a ser utilizado em cada requisição
  • AddDefaultParameter: adiciona um parâmetro padrâo a ser utilizado em cada requisição
  • GetAsync<T>: realiza uma requisição HTTP GET, lançando um erro em caso de falha na requisição, e deserializa a resposta como tipo defnido
  • PostAsync<T>: realiza uma requisição HTTP POST, lançando um erro em caso de falha na requisição, e deserializa a resposta como tipo definido
  • Authenticator: propriedade onde é definido o método de autenticação

Alguns métodos da classe RestRequest que são comumente utilizados:

  • AddQueryParameter: define parâmetros de query
  • AddHeader: define um cabeçalho
  • AddJsonBody: serializa o parâmetro como JSON, bem como define o Content-type como application/json.
  • Timeout: define um tempo de expiração da chamada personalizado

Existem diversos outros métodos e também onde é mostrado seus usos. Indico sempre ler a documentação das bibliotecas que esteja estudando. Leia aqui.


Um exemplo prático

Vou realizar uma chamada para Magic: Gathering API, que oferece uma API aberta para informações sobre o jogo de cartas Magic: The Gathering! Vai ser solicitado um filtro para a busca, e serão retornados os resultados com algumas informações das cartas.

Vou realizar uma chamada para um endpoint como https://api.magicthegathering.io/v1/cards?name=Jace, onde estou passando o parâmetro name para filtrar as cartas por nome (vai ser inserido pelo usuário).

Antes disso, vou criar uma classe que representa os dados que são retornados dessa API. O modelo é referenciado como CardsResponse e Cards.

namespace RestSharpDemo.Models
{
    internal class Card
    {
        public string Name { get; set; }
        public string ManaCost { get; set; }
        public decimal Cmc { get; set; }
        public string[] Colors { get; set; }
        public string Type { get; set; }
        public string ImageUrl { get; set; }
        public override string ToString()
        {
            return $"Name: {Name}, Mana Cost: {ManaCost}, Converted Mana Cost: {Cmc}, Colors: {string.Join('|', Colors)}, Type: {Type}, Image: {ImageUrl}";
        }
    }

    internal class CardsResponse
    {
        public Card[] Cards { get; set; }
    }
}

Com esses modelos criados, vamos solicitar o filtro ao usuário, e realizar a chamada utilizando o RestSharp, passando essa informação utilizando o parâmetro name.


using RestSharp;
using RestSharpDemo.Models;

Console.WriteLine("Type a card name or filter");
var filter = Console.ReadLine();

var client = new RestClient("https://api.magicthegathering.io/v1");

var request = new RestRequest("cards", Method.Get);
request.AddQueryParameter("name", filter);

var response = await client.GetAsync<CardsResponse>(request);

foreach (var card in response.Cards)
{
    Console.WriteLine(card);
}

Algumas coisas para notar:

  • A definição da URL base ao instanciar o RestClient
  • A definição do parâmetro name de tipo Query logo após instanciar o RestRequest.

Lembrar de adicionar o await na chamada de GetAsync<T>!

Bem simples, não acha?

Agora basta executar a aplicação Console, e verá o resultado a seguir.

Com a compreensão do funcionamento do RestSharp e dessa API, é possível por exemplo criar um app ou site de catálogo!


Inscreva-se na lista de espera do Método .NET Direto ao Ponto, um treinamento completo sobre C#, APIs com ASP.NET Core e Microsserviços:  Inscreva-se aqui.

São mais de 250 vídeo-aulas sobre temas como C#, ASP NET Core 5, EF Core, CQRS, Clean Architecture, Autenticação e autorização com JWT, Testes Unitários, Microsserviços, Performance em .NET, ASP NET Core e Azure, Docker, Carreira Internacional em .NET, e mais, em uma plataforma moderna e com emissão de certificados!


Desafio proposto

Que tal explorar outros recursos do Magic: The Gathering API? Se quiser algo mais avançado, poderia criar um banco de dados com esses dados e passar a chamar eles de lá após a primeira chamada ou mesmo ao se iniciar a aplicação popular o banco de dados com a listagem de cartas de uma coleção específica.

Outro desafio interessante seria refatorar alguma chamada que você já realize em seu projeto para utilizar o RestSharp!


Foi apresentado como se instala a biblioteca RestSharp, além de seu uso para requisições Get, se mostrando uma alternativa poderosa, popular e moderna para o consumo de APIs. Curtiu? Compartilhe o link com um colega!