Dukungan JSON Patch di API web ASP.NET Core

Artikel ini menjelaskan cara menangani permintaan JSON Patch di API web ASP.NET Core.

Dukungan Patch JSON di API web ASP.NET Core didasarkan pada System.Text.Json serialisasi, dan memerlukan Microsoft.AspNetCore.JsonPatch.SystemTextJson paket NuGet.

Apa itu standar JSON Patch?

Standar JSON Patch:

• Adalah format standar untuk menjelaskan perubahan yang akan diterapkan ke dokumen JSON.

• Didefinisikan dalam RFC 6902 dan banyak digunakan dalam API RESTful untuk melakukan pembaruan parsial pada sumber daya JSON.

• Menjelaskan urutan operasi yang mengubah dokumen JSON seperti:

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

Di aplikasi web, JSON Patch umumnya digunakan dalam operasi PATCH untuk melakukan pembaruan parsial sumber daya. Daripada mengirim seluruh sumber daya untuk pembaruan, klien dapat mengirim dokumen Patch JSON yang hanya berisi perubahan. Patching mengurangi ukuran payload dan meningkatkan efisiensi.

Untuk gambaran umum standar JSON Patch, lihat jsonpatch.com.

Dukungan JSON Patch di API web ASP.NET Core

Dukungan JSON Patch di API web ASP.NET Core didasarkan pada System.Text.Json serialisasi, dimulai dengan .NET 10, menerapkan Microsoft.AspNetCore.JsonPatch berdasarkan System.Text.Json serialisasi. Fitur ini:

• Memerlukan Microsoft.AspNetCore.JsonPatch.SystemTextJson paket NuGet.
• Selaras dengan praktik .NET modern dengan memanfaatkan pustaka System.Text.Json, yang telah dioptimalkan untuk .NET.
• Memberikan peningkatan performa dan pengurangan penggunaan memori dibandingkan dengan implementasi berbasis warisan Newtonsoft.Json. Untuk informasi selengkapnya tentang implementasi berbasis warisan Newtonsoft.Json, lihat versi .NET 9 dari artikel ini.

Note

Implementasi Microsoft.AspNetCore.JsonPatch berdasarkan serialisasi System.Text.Json bukanlah pengganti langsung untuk implementasi berbasis sistem lama Newtonsoft.Json. Ini tidak mendukung jenis dinamis, misalnya ExpandoObject.

Important

Standar Patch JSON memiliki risiko keamanan yang melekat. Karena risiko ini melekat pada standar Patch JSON, implementasi ASP.NET Core tidak mencoba mengurangi risiko keamanan yang melekat. Ini adalah tanggung jawab pengembang untuk memastikan bahwa dokumen Patch JSON aman untuk diterapkan ke objek target. Untuk informasi selengkapnya, lihat bagian Mitigasi Risiko Keamanan .

Mengaktifkan dukungan JSON Patch dengan System.Text.Json

Untuk mengaktifkan dukungan Patch JSON dengan System.Text.Json, instal Microsoft.AspNetCore.JsonPatch.SystemTextJson paket NuGet.

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

Paket ini menyediakan JsonPatchDocument<TModel> kelas untuk mewakili dokumen Patch JSON untuk objek jenis T dan logika kustom untuk menserialisasikan dan mendeserialisasi dokumen JSON Patch menggunakan System.Text.Json. Metode kunci kelas JsonPatchDocument<TModel> adalah ApplyTo(Object), yang menerapkan operasi patch ke objek target jenis T.

Kode metode tindakan menerapkan Patch JSON

Dalam pengontrol API, metode tindakan untuk JSON Patch:

• Diannotasikan dengan HttpPatchAttribute atribut .
• JsonPatchDocument<TModel>Menerima , biasanya dengan FromBodyAttribute.
• ApplyTo(Object) Panggilan pada dokumen patch untuk menerapkan perubahan.

Contoh metode Tindakan Pengontrol:

[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);
}

Kode dari aplikasi sampel ini berfungsi dengan model-model berikut: Customer dan 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();
    }
}

Langkah-langkah kunci metode tindakan sampel:

• Mengambil Data Pelanggan:
  • Metode mengambil Customer objek dari database AppDb menggunakan id yang disediakan.
  • Jika tidak ada Customer objek yang ditemukan, objek akan mengembalikan 404 Not Found respons.
• Terapkan Patch JSON:
  • Metode ApplyTo(Object) menerapkan operasi JSON Patch dari patchDoc ke objek Customer yang diambil.
  • Jika kesalahan terjadi selama aplikasi patch, seperti operasi atau konflik yang tidak valid, kesalahan tersebut ditangkap oleh delegasi penanganan kesalahan. Delegasi ini menambahkan pesan kesalahan ke ModelState menggunakan nama jenis objek yang terpengaruh dan pesan kesalahan.
• Validasi ModelState:
  • Setelah menerapkan patch, metode memeriksa ModelState untuk kesalahan.
  • Jika ModelState tidak valid, seperti karena kesalahan patch, maka 400 Bad Request merespons dengan memberikan kesalahan validasi.
• Kembalikan Pelanggan yang Diperbarui
  • Jika patch berhasil diterapkan dan ModelState valid, metode mengembalikan objek yang diperbarui Customer dalam respons.

Contoh respons kesalahan:

Contoh berikut menunjukkan isi 400 Bad Request respons untuk operasi Patch JSON saat jalur yang ditentukan tidak valid:

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

Menerapkan dokumen Patch JSON ke objek

Contoh berikut menunjukkan cara menggunakan ApplyTo(Object) metode untuk menerapkan dokumen Patch JSON ke objek.

Contoh: Menerapkan JsonPatchDocument<TModel> ke objek

Contoh berikut menunjukkan:

• Operasi add, replace, dan remove .
• Operasi pada properti berlapis.
• Menambahkan item baru ke array.
• Penggunaan Konverter Enum String JSON dalam dokumen patch 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));

Contoh sebelumnya menghasilkan output berikut dari objek yang diperbarui:

{
    "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"
        }
    ]
}

Metode ApplyTo(Object) ini umumnya mengikuti konvensi dan opsi System.Text.Json untuk memproses JsonPatchDocument<TModel>, termasuk perilaku yang dikontrol oleh opsi berikut:

• JsonNumberHandling: Apakah properti numerik ditafsirkan dari string.
• PropertyNameCaseInsensitive: Apakah nama properti peka huruf besar/kecil.

Perbedaan utama antara System.Text.Json dan implementasi baru JsonPatchDocument<TModel> :

• Jenis runtime objek target, bukan jenis yang dideklarasikan, menentukan patch properti ApplyTo(Object) mana.
• System.Text.Json deserialisasi bergantung pada jenis yang dinyatakan untuk mengidentifikasi properti yang memenuhi syarat.

Contoh: Menerapkan JsonPatchDocument dengan penanganan kesalahan

Ada berbagai kesalahan yang dapat terjadi saat menerapkan dokumen Patch JSON. Misalnya, objek target mungkin tidak memiliki properti yang ditentukan, atau nilai yang ditentukan mungkin tidak kompatibel dengan jenis properti.

JSON Patch mendukung test operasi, yang memeriksa apakah nilai tertentu sama dengan properti target. Jika tidak, itu akan mengembalikan kesalahan.

Contoh berikut menunjukkan cara menangani kesalahan ini dengan anggun.

Important

Objek yang diteruskan ke metode ApplyTo(Object) dimodifikasi langsung di tempatnya. Pemanggil bertanggung jawab dalam mengabaikan perubahan jika ada operasi yang gagal.

// 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));

Contoh sebelumnya menghasilkan output berikut:

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": []
}

Mengurangi risiko keamanan

Saat menggunakan Microsoft.AspNetCore.JsonPatch.SystemTextJson paket, sangat penting untuk memahami dan mengurangi potensi risiko keamanan. Bagian berikut menguraikan risiko keamanan yang diidentifikasi yang terkait dengan Patch JSON dan memberikan mitigasi yang direkomendasikan untuk memastikan penggunaan paket yang aman.

Important

Ini bukan daftar ancaman yang lengkap. Pengembang aplikasi harus melakukan tinjauan model ancaman mereka sendiri untuk menentukan daftar komprehensif khusus aplikasi dan membuat mitigasi yang sesuai kebutuhan. Misalnya, aplikasi yang mengekspos koleksi ke operasi patch harus mempertimbangkan potensi serangan kompleksitas algoritma jika operasi tersebut menyisipkan atau menghapus elemen di awal koleksi.

Untuk meminimalkan risiko keamanan saat mengintegrasikan fungsionalitas JSON Patch ke dalam aplikasi mereka, pengembang harus:

• Jalankan model ancaman komprehensif untuk aplikasi mereka sendiri.
• Mengatasi ancaman yang diidentifikasi.
• Ikuti mitigasi yang direkomendasikan di bagian berikut.

Penolakan Layanan (DoS) melalui amplifikasi memori

• Skenario: Klien berbahaya mengirimkan copy operasi yang menduplikasi grafik objek besar beberapa kali, yang mengarah ke konsumsi memori yang berlebihan.
• Dampak: Potensi kondisi Out-Of-Memory (OOM), menyebabkan gangguan layanan.
• Mitigation:
  • Validasi dokumen JSON Patch masuk untuk ukuran dan struktur sebelum memanggil ApplyTo(Object).
  • Validasi harus spesifik untuk aplikasi, tetapi contoh validasi dapat terlihat mirip dengan yang berikut ini:

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();
    }
}

Pengacauan Logika Bisnis

• Skenario: Operasi patch dapat memanipulasi bidang dengan invarian implisit (misalnya, bendera internal, ID, atau bidang komputasi), melanggar batasan bisnis.
• Dampak: Masalah integritas data dan perilaku aplikasi yang tidak diinginkan.
• Mitigation:
  • Gunakan POCO (Objek CLR Lama Biasa) dengan properti yang ditentukan secara eksplisit yang aman untuk dimodifikasi.
    • Hindari mengekspos properti sensitif atau kritis keamanan di objek target.
    • Jika objek POCO tidak digunakan, validasi objek yang di-patch setelah menerapkan operasi untuk memastikan aturan bisnis dan invarian tidak dilanggar.

Autentikasi dan otorisasi

• Skenario: Klien yang tidak diautentikasi atau tidak sah mengirim permintaan Patch JSON berbahaya.
• Dampak: Akses tidak sah untuk memodifikasi data sensitif atau mengganggu perilaku aplikasi.
• Mitigation:
  • Lindungi titik akhir yang menerima permintaan JSON Patch dengan mekanisme autentikasi dan otorisasi yang tepat.
  • Batasi akses ke klien atau pengguna tepercaya dengan izin yang sesuai.

Mendapatkan kode

Melihat atau mengunduh kode sampel. (Cara mengunduh).

Untuk menguji sampel, jalankan aplikasi dan kirim permintaan HTTP dengan pengaturan berikut:

• URL: http://localhost:{port}/jsonpatch/jsonpatchwithmodelstate
• Metode HTTP: PATCH
• Judul: Content-Type: application/json-patch+json
• Isi: Salin dan tempel salah satu sampel dokumen patch JSON dari folder proyek JSON .

Sumber daya tambahan

• Spesifikasi metode IETF RFC 5789 PATCH
• Spesifikasi IETF RFC 6902 JSON Patch
• IETF RFC 6901 JSON Pointer
• ASP.NET kode sumber Core JSON Patch