Consumir um serviço Web baseado em REST

Navegar na amostra

A Transferência de Estado Representacional (REST) é um estilo de arquitetura para a criação de serviços Web. As solicitações REST normalmente são feitas por HTTPS usando os mesmos verbos HTTP que os navegadores da Web usam para recuperar páginas da Web e enviar dados para servidores. Os verbos são:

• GET – essa operação é usada para recuperar dados do serviço Web.
• POST – essa operação é usada para criar um novo item de dados no serviço Web.
• PUT – essa operação é usada para atualizar um item de dados no serviço Web.
• PATCH – essa operação é usada para atualizar um item de dados no serviço Web descrevendo um conjunto de instruções sobre como o item deve ser modificado.
• DELETE – essa operação é usada para excluir um item de dados no serviço Web.

As APIs de serviço Web que aderem ao REST são definidas usando:

• Um URI de base.
• Métodos HTTP, como GET, POST, PUT, PATCH ou DELETE.
• Um tipo de mídia para os dados, como JSON (JavaScript Object Notation).

Os serviços Web baseados em REST normalmente usam mensagens JSON para retornar dados ao cliente. JSON é um formato de intercâmbio de dados baseado em texto que produz cargas compactas, o que resulta em requisitos de largura de banda reduzidos ao enviar dados. A simplicidade do REST ajudou a torná-lo o principal método para acessar serviços Web em aplicativos móveis.

Operações de serviço Web

O serviço REST de exemplo é escrito usando ASP.NET Core e fornece as seguintes operações:

O aplicativo .NET MAUI e o serviço Web usam a TodoItem classe para modelar os dados exibidos e enviados para o serviço Web para armazenamento:

public class TodoItem
{
    public string ID { get; set; }
    public string Name { get; set; }
    public string Notes { get; set; }
    public bool Done { get; set; }
}

A ID propriedade é usada para identificar exclusivamente cada TodoItem objeto e é usada pelo serviço Web para identificar dados a serem atualizados ou excluídos. Por exemplo, para excluir o TodoItem cujo ID é aaaabbbb-0000-cccc-1111-dddd2222eeee, o aplicativo .NET MAUI envia uma solicitação DELETE para https://hostname/api/todoitems/aaaabbbb-0000-cccc-1111-dddd2222eeee.

Quando a estrutura da API Web recebe uma solicitação, ela roteia a solicitação para uma ação. Essas ações são métodos públicos na TodoItemsController classe. A estrutura da API Web usa middleware de roteamento para corresponder às URLs de solicitações de entrada e mapeá-las para ações. As APIs REST devem usar o roteamento de atributo para modelar a funcionalidade do aplicativo como um conjunto de recursos cujas operações são representadas por verbos HTTP. O roteamento de atributo usa um conjunto de atributos para mapear ações diretamente para modelos de rota. Para obter mais informações sobre o roteamento de atributos, consulte Roteamento de atributo para APIs REST. Para obter mais informações sobre como criar o serviço REST usando ASP.NET Core, consulte Criando serviços de back-end para aplicativos móveis nativos.

Criar o objeto HTTPClient

Um aplicativo de interfaz de usuário de aplicativo de várias plataformas do .NET (.NET MAUI) pode consumir um serviço web baseado em REST enviando solicitações para o serviço web com a classe HttpClient. Essa classe fornece funcionalidade para enviar solicitações HTTP e receber respostas HTTP de um recurso identificado por URI. Cada solicitação é enviada como uma operação assíncrona.

O HttpClient objeto deve ser declarado no nível da classe para que ele resida enquanto o aplicativo precisar fazer solicitações HTTP:

public class RestService
{
    HttpClient _client;
    JsonSerializerOptions _serializerOptions;

    public List<TodoItem> Items { get; private set; }

    public RestService()
    {
        _client = new HttpClient();
        _serializerOptions = new JsonSerializerOptions
        {
            PropertyNamingPolicy = JsonNamingPolicy.CamelCase,
            WriteIndented = true
        };
    }
    ...
}

O JsonSerializerOptions objeto é usado para configurar a formatação do conteúdo JSON que é recebido e enviado para o serviço Web. Para obter mais informações, consulte Como instanciar instâncias JsonSerializerOptions com System.Text.Json.

Obter dados

O HttpClient.GetAsync método é usado para enviar uma solicitação GET para o serviço Web especificado pelo URI e, em seguida, receber a resposta do serviço Web:

public async Task<List<TodoItem>> RefreshDataAsync()
{
    Items = new List<TodoItem>();

    Uri uri = new Uri(string.Format(Constants.RestUrl, string.Empty));
    try
    {
        HttpResponseMessage response = await _client.GetAsync(uri);
        if (response.IsSuccessStatusCode)
        {
            string content = await response.Content.ReadAsStringAsync();
            Items = JsonSerializer.Deserialize<List<TodoItem>>(content, _serializerOptions);
        }
    }
    catch (Exception ex)
    {
        Debug.WriteLine(@"\tERROR {0}", ex.Message);
    }

    return Items;
}

Os dados são recebidos do serviço Web como um HttpResponseMessage objeto. Ele contém informações sobre a resposta, incluindo o código de status, os cabeçalhos e qualquer conteúdo. O serviço REST envia um código de status HTTP em sua resposta, que pode ser obtido da HttpResponseMessage.IsSuccessStatusCode propriedade, para indicar se a solicitação HTTP foi bem-sucedida ou falhou. Para esta operação, o serviço REST envia o código de status HTTP 200 (OK) na resposta, o que indica que a solicitação foi bem-sucedida e que as informações solicitadas estão na resposta.

Se a operação HTTP tiver sido bem-sucedida, o conteúdo da resposta será lido. A HttpResponseMessage.Content propriedade representa o conteúdo da resposta e é do tipo HttpContent. A HttpContent classe representa o corpo HTTP e os cabeçalhos de conteúdo, como Content-Type e Content-Encoding. Em seguida, o conteúdo é lido em um string usando o método HttpContent.ReadAsStringAsync. Em seguida, o string é desserializado de JSON para um List de objetos TodoItem.

Criar dados

O HttpClient.PostAsync método é usado para enviar uma solicitação POST para o serviço Web especificado pelo URI e, em seguida, para receber a resposta do serviço Web:

public async Task SaveTodoItemAsync(TodoItem item, bool isNewItem = false)
{
    Uri uri = new Uri(string.Format(Constants.RestUrl, string.Empty));

    try
    {
        string json = JsonSerializer.Serialize<TodoItem>(item, _serializerOptions);
        StringContent content = new StringContent(json, Encoding.UTF8, "application/json");

        HttpResponseMessage response = null;
        if (isNewItem)
            response = await _client.PostAsync(uri, content);
        else
            response = await _client.PutAsync(uri, content);

        if (response.IsSuccessStatusCode)
            Debug.WriteLine(@"\tTodoItem successfully saved.");
    }
    catch (Exception ex)
    {
        Debug.WriteLine(@"\tERROR {0}", ex.Message);
    }
}

Neste exemplo, a TodoItem instância é serializada para um payload JSON para ser enviado para o serviço Web. Esse payload é então inserido no corpo HTTP que será enviado ao serviço web antes que a solicitação seja feita com o método PostAsync.

O serviço REST envia um código de status HTTP em sua resposta, que pode ser obtido da HttpResponseMessage.IsSuccessStatusCode propriedade, para indicar se a solicitação HTTP foi bem-sucedida ou falhou. As respostas típicas para esta operação são:

• 201 (CREATED) – a solicitação resultou na criação de um novo recurso antes do envio da resposta.
• 400 (SOLICITAÇÃO INCORRETA) – a solicitação não é compreendida pelo servidor.
• 409 (CONFLITO) – a solicitação não pôde ser realizada devido a um conflito no servidor.

Atualizar dados

O HttpClient.PutAsync método é usado para enviar uma solicitação PUT para o serviço Web especificado pelo URI e, em seguida, receber a resposta do serviço Web:

public async Task SaveTodoItemAsync(TodoItem item, bool isNewItem = false)
{
  ...
  response = await _client.PutAsync(uri, content);
  ...
}

A operação do PutAsync método é idêntica ao PostAsync método usado para criar dados no serviço Web. No entanto, as possíveis respostas enviadas do serviço Web diferem.

O serviço REST envia um código de status HTTP em sua resposta, que pode ser obtido da HttpResponseMessage.IsSuccessStatusCode propriedade, para indicar se a solicitação HTTP foi bem-sucedida ou falhou. As respostas típicas para esta operação são:

• 204 (SEM CONTEÚDO) – a solicitação foi processada com êxito e a resposta está intencionalmente em branco.
• 400 (SOLICITAÇÃO INCORRETA) – a solicitação não é compreendida pelo servidor.
• 404 (NÃO ENCONTRADO) – o recurso solicitado não existe no servidor.

Excluir dados

O HttpClient.DeleteAsync método é usado para enviar uma solicitação DELETE para o serviço Web especificado pelo URI e, em seguida, receber a resposta do serviço Web:

public async Task DeleteTodoItemAsync(string id)
{
    Uri uri = new Uri(string.Format(Constants.RestUrl, id));

    try
    {
        HttpResponseMessage response = await _client.DeleteAsync(uri);
        if (response.IsSuccessStatusCode)
            Debug.WriteLine(@"\tTodoItem successfully deleted.");
    }
    catch (Exception ex)
    {
        Debug.WriteLine(@"\tERROR {0}", ex.Message);
    }
}

O serviço REST envia um código de status HTTP em sua resposta, que pode ser obtido da HttpResponseMessage.IsSuccessStatusCode propriedade, para indicar se a solicitação HTTP foi bem-sucedida ou falhou. As respostas típicas para esta operação são:

• 204 (SEM CONTEÚDO) – a solicitação foi processada com êxito e a resposta está intencionalmente em branco.
• 400 (SOLICITAÇÃO INCORRETA) – a solicitação não é compreendida pelo servidor.
• 404 (NÃO ENCONTRADO) – o recurso solicitado não existe no servidor.

Desenvolvimento local

Se você estiver desenvolvendo um serviço Web REST localmente com uma estrutura como ASP.NET API Web Core, poderá depurar seu serviço Web e o aplicativo MAUI do .NET ao mesmo tempo. Nesse cenário, para consumir seu serviço Web por HTTP de emuladores Android e simuladores de iOS, você deve habilitar o tráfego HTTP de texto limpo em seu aplicativo .NET MAUI. Para obter mais informações, consulte Conectar-se a serviços Web locais de emuladores Android e simuladores iOS.