Compatibilidad con JSON Patch en la API web de ASP.NET Core

En este artículo se explica cómo administrar solicitudes JSON Patch en una API web ASP.NET Core.

La compatibilidad con JSON Patch en la API web de ASP.NET Core se basa en la serialización de System.Text.Json y requiere el paquete NuGet Microsoft.AspNetCore.JsonPatch.SystemTextJson.

¿Qué es el estándar JSON Patch?

El estándar de parche JSON:

• Es un formato estándar para describir los cambios que se aplicarán a un documento JSON.

• Se define en RFC 6902 y se usa ampliamente en las API DE RESTful para realizar actualizaciones parciales en los recursos JSON.

• Describe una secuencia de operaciones que modifican un documento JSON como:

  • add
  • remove
  • replace
  • move
  • copy
  • test

En las aplicaciones web, JSON Patch se utiliza comúnmente en una operación PATCH para realizar actualizaciones parciales de un recurso. En lugar de enviar todo el recurso para una actualización, los clientes pueden enviar un documento de revisión JSON que contenga solo los cambios. La aplicación de parches reduce el tamaño de la carga y mejora la eficiencia.

Para obtener información general sobre el estándar de revisión JSON, consulte jsonpatch.com.

Compatibilidad con JSON Patch en la API web de ASP.NET Core

El soporte de JSON Patch en la API web ASP.NET Core se basa en serialización System.Text.Json, a partir de .NET 10, implementando Microsoft.AspNetCore.JsonPatch basado en serialización System.Text.Json. Esta característica:

• Requiere el Microsoft.AspNetCore.JsonPatch.SystemTextJson paquete NuGet.
• Se alinea con las prácticas modernas de .NET aprovechando la System.Text.Json biblioteca, que está optimizada para .NET.
• Proporciona un rendimiento mejorado y un uso reducido de memoria en comparación con la implementación basada en la herencia Newtonsoft.Json. Para obtener más información sobre la implementación basada en herencia Newtonsoft.Json, consulte la versión de .NET 9 de este artículo.

Note

La implementación de Microsoft.AspNetCore.JsonPatch basada en la serialización de System.Text.Json no es un reemplazo directo para la implementación basada en Newtonsoft.Json heredada. No admite tipos dinámicos, por ejemplo ExpandoObject.

Important

El estándar json Patch tiene riesgos de seguridad inherentes. Dado que estos riesgos son inherentes al estándar de revisión JSON, la implementación de ASP.NET Core no intenta mitigar los riesgos de seguridad inherentes. Es responsabilidad del desarrollador asegurarse de que el documento de revisión JSON es seguro para aplicarlo al objeto de destino. Para obtener más información, consulte la sección Mitigación de riesgos de seguridad .

Habilitar compatibilidad con parches JSON con System.Text.Json

Para habilitar la compatibilidad con los parches JSON con System.Text.Json, instale el paquete NuGet Microsoft.AspNetCore.JsonPatch.SystemTextJson.

dotnet add package Microsoft.AspNetCore.JsonPatch.SystemTextJson --prerelease

Este paquete proporciona una clase para representar un JsonPatchDocument<TModel> documento de revisión JSON para objetos de tipo T y lógica personalizada para serializar y deserializar documentos de revisión JSON mediante System.Text.Json. El método clave de la JsonPatchDocument<TModel> clase es ApplyTo(Object), que aplica las operaciones de revisión a un objeto de destino de tipo T.

Código del método de acción que aplica un parche JSON

En un controlador de API, un método de acción para JSON Patch:

• Se anota con el atributo HttpPatchAttribute.
• Acepta JsonPatchDocument<TModel>, normalmente con FromBodyAttribute.
• Llama a ApplyTo(Object) en el documento de revisión para aplicar los cambios.

Ejemplo de método de acción del controlador:

[HttpPatch("{id}", Name = "UpdateCustomer")]
public IActionResult Update(AppDb db, string id, [FromBody] JsonPatchDocument<Customer> patchDoc)
{
    // Retrieve the customer by ID
    var customer = db.Customers.FirstOrDefault(c => c.Id == id);

    // Return 404 Not Found if customer doesn't exist
    if (customer == null)
    {
        return NotFound();
    }

    patchDoc.ApplyTo(customer, jsonPatchError =>
        {
            var key = jsonPatchError.AffectedObject.GetType().Name;
            ModelState.AddModelError(key, jsonPatchError.ErrorMessage);
        }
    );

    if (!ModelState.IsValid)
    {
        return BadRequest(ModelState);
    }

    return new ObjectResult(customer);
}

Este código de la aplicación de ejemplo funciona con los siguientes Customer modelos y Order :

namespace App.Models;

public class Customer
{
    public string Id { get; set; }
    public string? Name { get; set; }
    public string? Email { get; set; }
    public string? PhoneNumber { get; set; }
    public string? Address { get; set; }
    public List<Order>? Orders { get; set; }

    public Customer()
    {
        Id = Guid.NewGuid().ToString();
    }
}

namespace App.Models;

public class Order
{
    public string Id { get; set; }
    public DateTime? OrderDate { get; set; }
    public DateTime? ShipDate { get; set; }
    public decimal TotalAmount { get; set; }

    public Order()
    {
        Id = Guid.NewGuid().ToString();
    }
}

Pasos clave del método de acción de ejemplo:

• Recupere el cliente:
  • El método recupera un Customer objeto de la base de datos AppDb mediante el identificador proporcionado.
  • Si no se encuentra ningún Customer objeto, devuelve una 404 Not Found respuesta.
• Aplicar JSON Patch:
  • El método ApplyTo(Object) aplica las operaciones de parche JSON del patchDoc al objeto recuperado Customer.
  • Si se producen errores durante la aplicación del parche, como operaciones o conflictos no válidos, se capturan mediante un delegado de control de errores. Este delegado agrega mensajes de error al ModelState utilizando el nombre de tipo del objeto afectado y el mensaje de error.
• Validar ModelState:
  • Después de aplicar el parche, el método comprueba el ModelState en busca de errores.
  • Si ModelState es inválido, debido a errores de parche, devuelve una respuesta 400 Bad Request con los errores de validación.
• Devuelve el cliente actualizado:
  • Si la revisión se aplica correctamente y ModelState es válida, el método devuelve el objeto actualizado Customer en la respuesta.

Respuesta de error de ejemplo:

En el ejemplo siguiente se muestra el cuerpo de una respuesta para una operación de parcheo JSON cuando la ruta especificada no es válida.

{
  "Customer": [
    "The target location specified by path segment 'foobar' was not found."
  ]
}

Aplicación de un documento de revisión JSON a un objeto

En los ejemplos siguientes se muestra cómo usar el ApplyTo(Object) método para aplicar un documento de revisión JSON a un objeto .

Ejemplo: Aplicar un JsonPatchDocument<TModel> a un objeto

En el ejemplo siguiente se muestra:

• Las operaciones add, replace, y remove.
• Operaciones sobre propiedades anidadas.
• Agregar un nuevo elemento a una matriz.
• Uso de un convertidor de enumeración de cadenas JSON en un documento de parche JSON.

// Original object
var person = new Person {
    FirstName = "John",
    LastName = "Doe",
    Email = "johndoe@gmail.com",
    PhoneNumbers = [new() {Number = "123-456-7890", Type = PhoneNumberType.Mobile}],
    Address = new Address
    {
        Street = "123 Main St",
        City = "Anytown",
        State = "TX"
    }
};

// Raw JSON patch document
string jsonPatch = """
[
    { "op": "replace", "path": "/FirstName", "value": "Jane" },
    { "op": "remove", "path": "/Email"},
    { "op": "add", "path": "/Address/ZipCode", "value": "90210" },
    { "op": "add", "path": "/PhoneNumbers/-", "value": { "Number": "987-654-3210",
                                                                "Type": "Work" } }
]
""";

// Deserialize the JSON patch document
var patchDoc = JsonSerializer.Deserialize<JsonPatchDocument<Person>>(jsonPatch);

// Apply the JSON patch document
patchDoc!.ApplyTo(person);

// Output updated object
Console.WriteLine(JsonSerializer.Serialize(person, serializerOptions));

El ejemplo anterior da como resultado la siguiente salida del objeto actualizado:

{
    "firstName": "Jane",
    "lastName": "Doe",
    "address": {
        "street": "123 Main St",
        "city": "Anytown",
        "state": "TX",
        "zipCode": "90210"
    },
    "phoneNumbers": [
        {
            "number": "123-456-7890",
            "type": "Mobile"
        },
        {
            "number": "987-654-3210",
            "type": "Work"
        }
    ]
}

El método ApplyTo(Object) generalmente sigue las convenciones y opciones de System.Text.Json para procesar el JsonPatchDocument<TModel>, incluido el comportamiento controlado por las siguientes opciones:

• JsonNumberHandling: indica si las propiedades numéricas se leen de cadenas.
• PropertyNameCaseInsensitive: Si los nombres de las propiedades distinguen entre mayúsculas y minúsculas.

Diferencias clave entre System.Text.Json y la nueva JsonPatchDocument<TModel> implementación:

• El tipo en tiempo de ejecución del objeto destino, no el tipo declarado, determina qué propiedades ApplyTo(Object) parchea.
• System.Text.Json la deserialización se basa en el tipo declarado para identificar las propiedades elegibles.

Ejemplo: Aplicación de jsonPatchDocument con control de errores

Hay varios errores que pueden producirse al aplicar un documento de JSON Patch. Por ejemplo, es posible que el objeto de destino no tenga la propiedad especificada o que el valor especificado no sea compatible con el tipo de propiedad.

JSON Patch admite la test operación, que comprueba si un valor especificado es igual a la propiedad de destino. Si no es así, devuelve un error.

En el ejemplo siguiente se muestra cómo controlar estos errores correctamente.

Important

El objeto pasado al método ApplyTo(Object) se modifica en el lugar. El autor de la llamada es responsable de descartar los cambios si alguna operación falla.

// Original object
var person = new Person {
    FirstName = "John",
    LastName = "Doe",
    Email = "johndoe@gmail.com"
};

// Raw JSON patch document
string jsonPatch = """
[
    { "op": "replace", "path": "/Email", "value": "janedoe@gmail.com"},
    { "op": "test", "path": "/FirstName", "value": "Jane" },
    { "op": "replace", "path": "/LastName", "value": "Smith" }
]
""";

// Deserialize the JSON patch document
var patchDoc = JsonSerializer.Deserialize<JsonPatchDocument<Person>>(jsonPatch);

// Apply the JSON patch document, catching any errors
Dictionary<string, string[]>? errors = null;
patchDoc!.ApplyTo(person, jsonPatchError =>
    {
        errors ??= new ();
        var key = jsonPatchError.AffectedObject.GetType().Name;
        if (!errors.ContainsKey(key))
        {
            errors.Add(key, new string[] { });
        }
        errors[key] = errors[key].Append(jsonPatchError.ErrorMessage).ToArray();
    });
if (errors != null)
{
    // Print the errors
    foreach (var error in errors)
    {
        Console.WriteLine($"Error in {error.Key}: {string.Join(", ", error.Value)}");
    }
}

// Output updated object
Console.WriteLine(JsonSerializer.Serialize(person, serializerOptions));

El ejemplo anterior da como resultado la siguiente salida:

Error in Person: The current value 'John' at path 'FirstName' is not equal 
to the test value 'Jane'.
{
    "firstName": "John",
    "lastName": "Smith",              <<< Modified!
    "email": "janedoe@gmail.com",     <<< Modified!
    "phoneNumbers": []
}

Mitigación de riesgos de seguridad

Al usar el Microsoft.AspNetCore.JsonPatch.SystemTextJson paquete, es fundamental comprender y mitigar los posibles riesgos de seguridad. En las secciones siguientes se describen los riesgos de seguridad identificados asociados a la revisión JSON y se proporcionan mitigaciones recomendadas para garantizar el uso seguro del paquete.

Important

Esta no es una lista exhaustiva de amenazas. Los desarrolladores de aplicaciones deben llevar a cabo sus propias revisiones del modelo de amenazas para determinar una lista completa específica de la aplicación y elaborar mitigaciones adecuadas según sea necesario. Por ejemplo, las aplicaciones que exponen colecciones a operaciones de revisión deben tener en cuenta la posibilidad de ataques de complejidad algorítmica si esas operaciones insertan o quitan elementos al principio de la colección.

Para minimizar los riesgos de seguridad al integrar la funcionalidad JSON Patch en sus aplicaciones, los desarrolladores deben:

• Ejecute modelos de amenazas completos para sus propias aplicaciones.
• Abordar las amenazas identificadas.
• Siga las mitigaciones recomendadas en las secciones siguientes.

Denegación de servicio (DoS) a través de la amplificación de memoria

• Escenario: un cliente malintencionado envía una copy operación que duplica gráficos de objetos grandes varias veces, lo que conduce a un consumo excesivo de memoria.
• Impacto: Posibles condiciones Out-Of-Memory (OOM), causando interrupciones del servicio.
• Mitigation:
  • Valide los documentos de parche JSON entrantes en cuanto a tamaño y estructura antes de llamar a ApplyTo(Object).
  • La validación debe ser específica de la aplicación, pero una validación de ejemplo puede ser similar a la siguiente:

public void Validate(JsonPatchDocument<T> patch)
{
    // This is just an example. It's up to the developer to make sure that
    // this case is handled properly, based on the app needs.
    if (patch.Operations.Where(op=>op.OperationType == OperationType.Copy).Count()
                              > MaxCopyOperationsCount)
    {
        throw new InvalidOperationException();
    }
}

Subversión de la lógica empresarial

• Escenario: las operaciones de parcheo pueden manipular campos con invariables implícitas (por ejemplo, marcas internas, identificadores o campos calculados), violando restricciones empresariales.
• Impacto: problemas de integridad de datos y comportamiento de la aplicación no deseado.
• Mitigation:
  • Use POCOs (Plain Old CLR Objects) con propiedades definidas explícitamente que resulten seguras de modificar.
    • Evite exponer propiedades confidenciales o críticas para la seguridad en el objeto de destino.
    • Si no se usa un objeto POCO, valide el objeto modificado después de aplicar operaciones, asegurándose de que no se infringen las reglas empresariales y las invariantes.

Autenticación y autorización

• Escenario: clientes no autenticados o no autorizados envían solicitudes maliciosas de parche JSON.
• Impacto: acceso no autorizado para modificar datos confidenciales o interrumpir el comportamiento de la aplicación.
• Mitigation:
  • Proteja los puntos de conexión que aceptan solicitudes de revisión JSON con mecanismos de autenticación y autorización adecuados.
  • Restrinja el acceso a clientes o usuarios de confianza con los permisos adecuados.

Obtención del código

Vea o descargue el código de ejemplo. (Método de descarga).

Para probar el ejemplo, ejecute la aplicación y envíe solicitudes HTTP con la configuración siguiente:

• Dirección URL: http://localhost:{port}/jsonpatch/jsonpatchwithmodelstate
• Método HTTP: PATCH
• Encabezado: Content-Type: application/json-patch+json
• Cuerpo: Copie y pegue uno de los ejemplos de documento de revisión de JSON de la carpeta del proyecto JSON.

Recursos adicionales

• Especificación del método PATCH de IETF RFC 5789
• Especificación del método JSON PATCH de IETF RFC 6902
• Puntero JSON del RFC 6901 de IETF
• Código fuente de JSON Patch para ASP.NET Core