feat!: Drop Response.created(body, location) overload

Location had a dedicated parameter slot; every other header went through
withHeader. A real footgun — callers reached for Response.created(body) and
forgot the Location header. Forcing .withHeader("Location", uri) for
symmetry removes the trap.

Author: thced

README.md

@@ -66,7 +66,8 @@ Response.empty();                                 // 204 No Content, no body
 Response.status(200);                             // 200 OK, no body
 Response.ok(Map.of("id", "42"));                  // 200 OK, JSON body via TypeMapper
 Response.created(newResource);                    // 201 Created, JSON body
-Response.created(newResource, "/things/42");      // 201 Created + Location header
+Response.created(newResource)
+    .withHeader("Location", "/things/42");        // 201 Created + Location header
 Response.accepted();                              // 202 Accepted, no body
 Response.accepted(Map.of("jobId", "job-42"));     // 202 Accepted, JSON body
 Response.notFound();                              // 404 Not Found, no body

src/main/java/com/retailsvc/http/Response.java

@@ -55,17 +55,12 @@ public static Response ok(Object body) {
     return new Response(HTTP_OK, body, null, Map.of());
   }
 
-  /** {@code 201 Created} with {@code body} serialised as JSON. */
-  public static Response created(Object body) {
-    return new Response(HTTP_CREATED, body, null, Map.of());
-  }
-
   /**
-   * {@code 201 Created} with {@code body} as JSON and a {@code Location} header — the canonical
-   * shape for a POST that creates a new resource.
+   * {@code 201 Created} with {@code body} serialised as JSON. Add a {@code Location} header for the
+   * new resource via {@link #withHeader(String, String) withHeader("Location", uri)}.
    */
-  public static Response created(Object body, String location) {
-    return new Response(HTTP_CREATED, body, null, Map.of("Location", location));
+  public static Response created(Object body) {
+    return new Response(HTTP_CREATED, body, null, Map.of());
   }
 
   /** {@code 202 Accepted} with no body. Use for fire-and-forget async work. */

src/test/java/com/retailsvc/http/ResponseTest.java

@@ -40,8 +40,8 @@ void createdWithBody() {
   }
 
   @Test
-  void createdWithLocation() {
-    Response r = Response.created(Map.of("id", "x-1"), "/things/x-1");
+  void createdWithLocationViaWithHeader() {
+    Response r = Response.created(Map.of("id", "x-1")).withHeader("Location", "/things/x-1");
 
     assertThat(r.status()).isEqualTo(HTTP_CREATED);
     assertThat(r.headers()).containsEntry("Location", "/things/x-1");