Add PATCH to tutorial

[tdykstra]

Description

Verbatim:

It doesn't have example of a PATCH operation. Microsoft added MapPatch support in .net7 but didn't added an example of it in this documentation page. It would be useful if Microsoft add an example which uses MapPut and JsonPatch in the net core template for minimal api.

Page URL

https://learn.microsoft.com/en-us/aspnet/core/tutorials/min-web-api?view=aspnetcore-8.0&tabs=visual-studio

Content source URL

https://github.com/dotnet/AspNetCore.Docs/blob/main/aspnetcore/tutorials/min-web-api.md

Document ID

ab408035-6313-a183-9940-32de00e0e977

Article author

@wadepickett

---

Associated WorkItem - 508916

[wadepickett]

AI analysis test run by wadepickett
Prompt: verify-issue-set-course-of-action_v.05.md
Model: GPT-4 Nov 2023

Issue Analysis: Add PATCH to tutorial

Issue Summary

This is a valid issue. The user reports that the minimal API tutorial for ASP.NET Core does not include an example for a PATCH operation, specifically using MapPatch and (optionally) JsonPatchDocument in the .NET minimal API template. PATCH support was introduced in .NET 7 but is not demonstrated in the current tutorial.

Issue Context and Validation

• Article evaluated: Tutorial: Create a minimal API with ASP.NET Core

• Source file path: aspnetcore/tutorials/min-web-api.md

• Current status:

  • No PATCH Example: The table and main API walkthrough provide GET, POST, PUT, DELETE; no PATCH endpoint is included for updating partial resources.
  • No mention of MapPatch or JsonPatch: The file does not show usage (sample code or instruction) for PATCH-specific minimal API patterns, nor how to apply JSON Patch documents.
  • Tutorial scope and audience (minimal API, .NET 6–9): The visible section of the tutorial is geared to basics and practical "CRUD" with PUT and POST, but PATCH is now a canonical REST verb and should be covered at least in .NET 7+ coverage.

• Recent related/overlapping issues:

  • Numerous closed or open issues on PATCH, MapPatch, and JsonPatch in the repo—but primarily in advanced topics, Blazor articles, or dedicated jsonpatch.md.
  • This tutorial still does not describe PATCH in the visual walkthrough or add a PATCH endpoint for minimal APIs.

• No effective workaround or cross-reference: The article does not redirect readers to dedicated PATCH or JsonPatch documentation, so discoverability in the tutorial context is poor.

• Has the issue already been addressed?

  • No. As of the latest HEAD, there is no PATCH sample or mention in the tutorial—confirmed by direct review of the min-web-api.md at HEAD and the accompanying sample code.

Affected File(s) and Section(s)

• File to update:

  • aspnetcore/tutorials/min-web-api.md

• Sections impacted:

  • "Overview" Table: Add PATCH endpoint row
  • API Implementation Steps: Add PATCH endpoint code (ideally after PUT section)
  • Testing steps: Add PATCH example in .http file (VS/VS Code) and Swagger instructions

Recommended Documentation Update

1. Add PATCH endpoint to "Overview" Table:

   • Describe PATCH operation, request/response body requirements, and intent (partial resource update).

2. Provide PATCH minimal API sample code:

   • Add MapPatch endpoint to the example, updating partial fields for a todo item.
   • If using .NET 7+, optionally add an example using JsonPatchDocument<Todo> for advanced partial updates.

3. Update step-by-step instructions:

   • Include PATCH request sample (in .http file and in Swagger UI testing steps).
   • Demonstrate use and limitations of PATCH as compared to PUT.

4. Add a tip/note block:

   • e.g., [!NOTE] PATCH provides partial updates and can leverage JsonPatch for complex scenarios.

5. Reference dedicated guidance:

   • Cross-link to JsonPatch in ASP.NET Core web API for advanced scenarios.

Example Code or CLI Snippets (if applicable)

Basic PATCH with direct property assignment (Recommended for tutorial simplicity):

todoItems.MapPatch("/{id}", async (int id, TodoPatchDto patch, TodoDb db) =>
{
    var todoItem = await db.Todos.FindAsync(id);
    if (todoItem is null) return Results.NotFound();
    if (patch.Name is not null) todoItem.Name = patch.Name;
    if (patch.IsComplete is not null) todoItem.IsComplete = patch.IsComplete.Value;
    await db.SaveChangesAsync();
    return Results.NoContent();
});

Where TodoPatchDto is:

public class TodoPatchDto
{
    public string? Name { get; set; }
    public bool? IsComplete { get; set; }
}

Sample PATCH request in TodoApi.http file:

PATCH {{TodoApi_HostAddress}}/todoitems/1
Content-Type: application/json

{
  "name": "run errands"
}

Tip block (docs note) suggestion:

[!NOTE]
PATCH operations allow partial updates to resources. For more advanced partial updates, see [JsonPatch in ASP.NET Core web API](xref:web-api/jsonpatch).

Copilot Action Plan

Suggested Action Plan for Consideration

• File to Edit: aspnetcore/tutorials/min-web-api.md

• Section:

  • "Overview" API Table (add PATCH)
  • After "Examine the PUT endpoint", add: "Examine the PATCH endpoint" and "Test the PATCH endpoint"
  • .http file and Swagger steps (include PATCH usage)

• Insertion Type:

  • Add API row to table
  • Insert code block for PATCH endpoint and DTO
  • Add .http/Swagger testing sample for PATCH

• Content Block Type: [!NOTE] (for PATCH partial update and JsonPatch cross-link)

• Example Code to Include: PATCH endpoint sample in C#, PATCH .http request sample

• Expected Output: Updated doc provides clear step-by-step guidance on PATCH operation in minimal APIs, including sample code and instructions for both .http and Swagger UI. Note highlights partial update pattern and advanced PATCH usage via JsonPatch.

• Do Not: Edit unrelated sections (GET, POST, DELETE, overall structure), overuse docs tip/important notes.

• Since PATCH was added in .NET 7, these changes should only be added to moniker version 7 to current of the article.

References and Links

• Issue: Add PATCH to tutorial
• Minimal API tutorial source file
• JsonPatch in ASP.NET Core web API
• MapPatch API reference
• Minimal APIs docs
• Swagger/OpenAPI docs