Consumindo APIs HTTP com Flurl

Neste artigo eu vou falar sobre o Flurl, uma biblioteca moderna que oferece funcionalidades de cliente HTTP e que tem uma sintaxe bem interessante que chamou minha atenção quando comecei a utilizar.

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 última que trato aqui.

Sobre o Flurl

O Flurl é uma biblioteca de cliente Http, que além de ser moderna e com sintaxe simples, também é altamente testável.

Você pode instalar o Flurl através do Gerenciador de pacotes NuGet ou pela .NET CLI, pode encontrar ambos comandos respectivamente abaixo. O pacote Flurl.Http é o que você utilizará efetivamente para as requisições HTTP, já que o pacote base Flurl é utilizado apenas para parsing de URLs.

Install-Package Flurl.Http -Version 3.2.0
dotnet add package Flurl.Http --version 3.2.0

Principais Métodos

O Flurl disponibiliza métodos de extensão ao tipo String, oferecendo uma interface moderna e fluída.

Alguns métodos utilizados:

  • SetQueryParams: define parâmetros de query
  • GetJsonAsync<T>: realiza uma requisição GET esperando um tipo T de retorno
  • PostJsonAsync: realiza um POST de um objeto JSON no corpo da requisição
  • WithHeader, WithHeaders: define um par de chave-valor ou um objeto para o cabeçalho, respectivamente.
  • WithTimeout: especifica timeout para a requisição
  • WithBasicAuth, WithOAuthBearerToken: permitem definir dados de autenticação

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 PokeApi, que oferece uma API aberta para informações sobre Pokemon!

Vou realizar uma chamada para o endpoint https://pokeapi.co/api/v2/pokemon?limit=151, onde estou passando o parâmetro limit para limitar a quantidade de registros retornados para os Pokemon da primeira geração (melhor geração na minha opinião…).

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

namespace FlurlExample.API.Models
{
    public class NamedAPIResourceList
    {
        public int Count { get; set; }
        public string Next { get; set; }
        public string Previous { get; set; }
        public NamedAPIResource[] Results { get; set; }
    }
}
namespace FlurlExample.API.Models
{
    public class NamedAPIResource
    {
        public string Name { get; set; }
        public string Url { get; set; }
    }
}

Com esses modelos criados, vamos para criar um endpoint da nossa API que vai retornar essas informações para uma requisição GET em api/pokemon. Vamos permitir também passar o parâmetro de query limit.

De início, é criado um Controller com uma Action Get vazia, que será onde adicionaremos a requisição para a API de Pokemon.

using Microsoft.AspNetCore.Mvc;

namespace FlurlExample.API.Controllers
{
    [Route("api/[controller]")]
    public class PokemonController : ControllerBase
    {
        [HttpGet]
        public IActionResult Get(int limit) {
            return Ok();
        }
    }
}

Após isso, é adicionado o código para realizar uma chamada GET, especificando o tipo NamedAPIResourceList, e adicionado o parâmetro de query chamado limit.

using System.Threading.Tasks;
using Flurl;
using Flurl.Http;
using FlurlExample.API.Models;
using Microsoft.AspNetCore.Mvc;

namespace FlurlExample.API.Controllers
{
    [Route("api/[controller]")]
    public class PokemonController : ControllerBase
    {
        [HttpGet]
        public async Task<IActionResult> Get(int limit) {
            var url = "https://pokeapi.co/api/v2/pokemon";

            var result = await url
                .SetQueryParams(new { limit = limit })
                .GetJsonAsync<NamedAPIResourceList>();

            return Ok(result);
        }
    }
}

Lembrar de adicionar o await na chamada de GetJsonAsync!

Bem fluído, não acha? Não precisamos especificar o HttpClient e tudo mais, apenas utilizar a chamada do método de extensão do tipo String e encadear o que for necessário.

Agora basta executar a aplicação, e acessar a URL https://localhost:5001/api/Pokemon?limit=151. Isso deverá retornar o resultado da seguinte imagem.

Retorno da chamada da API api/pokemon

Com isso feito, é possível realizar requisições seguintes utilizando a propriedade next do objeto, além de acessar os detalhes de cada Pokemon com a URL fornecida no NamedAPIResource.


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 quase 200 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, além de mini-cursos em Microsserviços, Performance em .NET, ASP NET Core e Azure, Docker, Carreira Internacional em .NET, e mais.


Desafio proposto

Que tal desenvolver uma API sobre os outros recursos da PokeApi, criando as chamadas usando o Flurl? 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.

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


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