ASP.NET Core - Atualização parcial com HTTP PATCH - I

  Hoje veremos como realizar a atualização parcial de um recurso usando os recursos do JSON PATCH e o atributo HttpPatch em uma Web API da ASP .NET Core 2.2.

Em outro artigo eu mostrei como realizar a atualização de um recurso usando o verbo HTTP PUT.

Ocorre que a atualização feita via HTTP PUT é uma atualização completa, ou seja, eu tenho que atualizar o curso por inteiro.  Assim, uma requisição PUT sempre contém um recurso completo. Isso é necessário porque, uma qualidade necessária das requisições PUT é ser idempotente - a qualidade de produzir o mesmo resultado, mesmo que a mesma solicitação seja feita várias vezes.

Neste artigo veremos uma forma de realizar a atualização parcial de um recurso usando o verbo HTTP PATCH.

Uma requisição PATCH é usada para fazer alterações em parte do recurso em um local mudando suas propriedades. Ele é usado para fazer pequenas atualizações nos recursos e não é necessário ser idempotente.

Isso significa que, se tivermos um recurso e quisermos atualizar apenas alguns campos, e não todos, esse é o método HTTP que devemos usar.

Como o HTTP PATCH funciona ?

O cliente da Web API deve enviar, no body (corpo) da requisição HTTP, informações que indicarão as alterações que ele deseja fazer no recurso. Em nosso caso, estamos interessados ​​em saber quais campos o cliente deseja atualizar e quais serão os novos valores desses campos.

Como o cliente vai nos enviar essa informação ?

Existe um padrão definido na RFC 6902 chamado "JSON Patch", que podemos usar com o HTTP PATCH.

Esse padrão define qual deve ser a estrutura do corpo da solicitação HTTP para indicar as mudanças que o cliente deseja fazer no recurso e define também um conjunto de operações a realizar que são:

Neste artigo vamos focar apenas na operação replace ou substituir que vamos usar para atualizar campos de um recurso.

A estrutura das requisições PATCH seguem um padrão semelhante, sendo expressa como uma lista de operações dentro de um array. A operação possui 3 propriedades:

  1. 'op'  - define o tipo de operação a ser realizada. Ex: add, remove, replace, etc.
  2. 'patch' - define o caminho da propriedade do objeto que você quer atingir. Ex: /nome
  3. 'value' - define o valor a ser usado na operação.

A seguir temos um exemplo de estrutura de uma requisição PATCH que altera o nome e a idade de um recurso usando a operação replace :

[
  { "op": "replace", "path": "/nome", "value": "Macoratti" },
  { "op": "replace", "path": "/idade", "value": "55" }
]

A grande vantagem em usar o JSON Patch é que ele é muito leve em sua carga, enviando apenas exatamente o que precisamos alterar no objeto.

Exemplo prático usando JSON Patch

Vamos entender melhor como funciona este recurso em um exemplo prático.

Vamos criar um projeto ASP .NET Core usando o template API no VS 2019 Community chamado Webapi_Patch1.

Vamos definir uma Web API para expor recursos da tabela Categorias existente no SQL Server 2012 no banco de dados Cadastro.

Após criar o projeto crie uma pasta Models no projeto e nesta pasta inclua :

1- A classe Categoria que representa o modelo de domínio anêmico:

public class Categoria
    {
        public int Id { get; set; }
        public string CategoriaNome { get; set; }
        public string CategoriaDescricao { get; set; }
    }

 

2- A classe de contexto AppDbContext que representa uma sessão com o banco de dados:

using Microsoft.EntityFrameworkCore;
namespace Webpi_Patch1.Models
{
    public class AppDbContext : DbContext
    {
        public AppDbContext(DbContextOptions<AppDbContext> options)
            : base(options)
        { }

        public DbSet<Categoria> Categorias { get; set; }
    }
}

Depois dessas definições abra o arquivo appsettings.json e defina string de conexão com o banco de dados:

{
  "ConnectionStrings": {
    "DefaultConnection": "Data Source=Macoratti;Initial Catalog=Cadastro;Integrated Security=True"
  },
  "Logging": {
    "LogLevel": {
      "Default": "Warning"
    }
  },
  "AllowedHosts": "*"
}

Abra o arquivo Startup.cs e altere o código do método ConfigureServices() incluindo o provedor do banco de dados e a string de conexão a ser usada:

.       public void ConfigureServices(IServiceCollection services)
        {
            services.AddDbContext<AppDbContext>(options =>
              options.UseSqlServer(Configuration.GetConnectionString("DefaultConnection")));
            services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_2);
        }

Assim temos tudo configurado para criar o controlador e definir o método para realizar a atualização parcial usando o método Patch.

Vamos ver isso na próxima parte do artigo.

"Porque o reino de Deus não é comida nem bebida, mas justiça, e paz, e alegria no Espírito Santo."
 Romanos 14:17

Referências:

José Carlos Macoratti