HTTP POST, PUT and PATCH — Creating and Updating Resources

POST creates resources, PUT replaces them entirely, and PATCH updates specific fields. Each has distinct semantics that both the server and client must respect. POST is the most common write operation; PUT and PATCH are used for updates but with important differences in how complete the request must be. Getting these right — including the correct status codes and proper partial update handling — is the mark of a well-designed REST API.

POST, PUT and PATCH #

[ApiController]
[Route("api/posts")]
public class PostsController(IPostService service) : ControllerBase
{
    // ── POST — create, return 201 with Location ────────────────────────────
    // POST /api/posts
    // Body: { "title": "New Post", "body": "Content...", "slug": "new-post" }
    [HttpPost]
    [ProducesResponseType(typeof(PostDto), 201)]
    [ProducesResponseType(typeof(ValidationProblemDetails), 400)]
    [ProducesResponseType(typeof(ProblemDetails), 409)]
    public async Task<ActionResult<PostDto>> Create(
        CreatePostRequest request, CancellationToken ct)
    {
        if (await service.SlugExistsAsync(request.Slug, ct))
            return Conflict(new { message = "Slug is already in use.", field = "slug" });

        var post = await service.CreateAsync(request, ct);
        return CreatedAtAction(nameof(GetById), new { id = post.Id }, post);
    }

    // ── PUT — full replace (all fields required) ──────────────────────────
    // PUT /api/posts/42
    // Body: ALL post fields (omitted fields are set to null/default)
    [HttpPut("{id:int}")]
    [ProducesResponseType(typeof(PostDto), 200)]
    [ProducesResponseType(404)]
    public async Task<ActionResult<PostDto>> Replace(
        int id, ReplacePostRequest request, CancellationToken ct)
    {
        var post = await service.ReplaceAsync(id, request, ct);
        return post is null ? NotFound() : Ok(post);
    }

    // ── PATCH — partial update (only send fields to change) ────────────────
    // PATCH /api/posts/42
    // Body: { "title": "Updated Title" }  — only the fields to update
    [HttpPatch("{id:int}")]
    [ProducesResponseType(typeof(PostDto), 200)]
    [ProducesResponseType(404)]
    public async Task<ActionResult<PostDto>> Update(
        int id, UpdatePostRequest request, CancellationToken ct)
    {
        var post = await service.UpdateAsync(id, request, ct);
        return post is null ? NotFound() : Ok(post);
    }
}

JSON Patch (RFC 6902) — Standards-Based PATCH #

// dotnet add package Microsoft.AspNetCore.Mvc.NewtonsoftJson
// (JsonPatchDocument requires Newtonsoft.Json in ASP.NET Core)

// ── JSON Patch request body ───────────────────────────────────────────────
// PATCH /api/posts/42
// Content-Type: application/json-patch+json
// [
//   { "op": "replace", "path": "/title", "value": "New Title" },
//   { "op": "remove",  "path": "/subtitle" },
//   { "op": "add",     "path": "/tags/-", "value": "dotnet" }
// ]

[HttpPatch("{id:int}")]
public async Task<ActionResult<PostDto>> Patch(
    int id,
    [FromBody] JsonPatchDocument<UpdatePostRequest> patchDoc,
    CancellationToken ct)
{
    var post = await service.GetByIdAsync(id, ct);
    if (post is null) return NotFound();

    var patchTarget = post.ToUpdateRequest();
    patchDoc.ApplyTo(patchTarget, ModelState);   // apply patch operations

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

    var updated = await service.UpdateAsync(id, patchTarget, ct);
    return Ok(updated);
}

Common Mistakes #

Mistake 1 — Using PUT when only updating some fields (clears non-sent fields) #

❌ Wrong — Angular sends PUT with only changed fields; all other fields silently cleared on server.

✅ Correct — use PATCH for partial updates; PUT only when replacing the complete resource.

Mistake 2 — Using the ID from the request body instead of the route (security issue) #

❌ Wrong — body ID could differ from route ID; wrong resource modified:

var post = await service.UpdateAsync(request.Id, request, ct);  // uses body ID — wrong!

✅ Correct — always use the route parameter ID: service.UpdateAsync(id, request, ct).