HTTP Methods

Every HTTP request carries two pieces of intent. The path says which thing you mean. The method says what you want done with it.

GET /api/employees/42 and DELETE /api/employees/42 name the same employee. One reads the record, one removes it. Nothing in the path distinguishes them, which is why the method is not decoration — it is half the meaning of the request.

Idempotency is about the state of the server, not about getting an identical response. A second DELETE /api/employees/42 will probably answer 404 rather than 204, and that is still idempotent — the employee is absent either way.

This matters because networks drop responses. A caller sends POST /api/orders, the order is created, and the reply never arrives. The caller cannot tell the difference between "the request never landed" and "the request worked and the answer was lost". Retrying is the natural response, and with POST it creates a second order.

The fix is an idempotency key: the caller generates a unique value for this attempt and sends it with the request. The server records the key alongside the result. If the same key arrives again, it returns the original result instead of creating anything. Retries become safe without changing what POST means.

POST /api/orders HTTP/1.1
Host: api.example.com
Content-Type: application/json
Idempotency-Key: 4b7d2c10-3f41-4a8e-9c62-b0e5f1d78a20

{ "employeeId": 42, "sku": "DESK-LAMP-01", "quantity": 2 }

HTTP/1.1 201 Created
Location: /api/orders/1042
Content-Type: application/json

{ "id": 1042, "employeeId": 42, "sku": "DESK-LAMP-01", "quantity": 2 }

• The caller invents the Idempotency-Key value, not the server. It identifies this attempt, so a retry of the same attempt reuses it and a genuinely new order gets a new one.
• The server stores the key with the created order id. A repeat of the same key returns 201 and the same order 1042 rather than creating 1043.
• Location tells the caller where the new order now lives. That is how the caller learns the address it did not get to choose.
• Nothing here makes POST idempotent in general. You have added a mechanism that recognises a duplicate attempt, which is a different and honest claim.

app.MapGet("/api/employees/{id:int}", async (int id, EmployeeService employees) =>
{
    var employee = await employees.FindAsync(id);
    return employee is null ? Results.NotFound() : Results.Ok(employee);
});

app.MapPost("/api/employees", async (CreateEmployeeRequest request, EmployeeService employees) =>
{
    var created = await employees.CreateAsync(request);
    return Results.Created($"/api/employees/{created.Id}", created);
});

app.MapPut("/api/employees/{id:int}", async (int id, ReplaceEmployeeRequest request, EmployeeService employees) =>
{
    var replaced = await employees.ReplaceAsync(id, request);
    return replaced ? Results.NoContent() : Results.NotFound();
});

app.MapDelete("/api/employees/{id:int}", async (int id, EmployeeService employees) =>
{
    await employees.DeleteAsync(id);
    return Results.NoContent();
});

• Four methods, one path pattern. The path never contains a word like get or delete, because the method already says it.
• MapGet returns the employee or a 404. A read never changes anything, which is what makes it cacheable and retryable by anything between the caller and you.
• MapPost returns 201 with a Location header, built with Results.Created. The server chose the id, so it has to tell the caller where the new record is.
• MapPut returns 204 No Content when the replacement succeeded. There is nothing useful to send back — the caller already has the values it just sent.
• MapDelete returns 204 whether or not the record was there. Answering the same way for a repeat keeps the endpoint pleasant to retry. Returning 404 for the second call is also defensible; pick one and apply it everywhere.