- consumer parsing failure
- generated client rusak
- retry salah
- cache salah
- pagination inconsistent
- breaking change yang tidak disadari
- observability sulit karena metadata hilang
- data leak karena DTO terlalu dekat ke entity/domain object

A response is not what your service knows.
A response is what your consumers are allowed to depend on.

@GET
@Path("/{quoteId}")
@Produces(MediaType.APPLICATION_JSON)
public QuoteResponse getQuote(@PathParam("quoteId") String quoteId) {
    return quoteService.getQuote(quoteId);
}

@POST
@Consumes(MediaType.APPLICATION_JSON)
@Produces(MediaType.APPLICATION_JSON)
public Response createQuote(CreateQuoteRequest request) {
    QuoteResponse response = quoteService.createQuote(request);

    return Response
        .status(Response.Status.CREATED)
        .header("Location", "/quotes/" + response.id())
        .entity(response)
        .build();
}

@GET
@Path("/{quoteId}")
public QuoteEntity getQuote(@PathParam("quoteId") String quoteId) {
    return quoteRepository.findById(quoteId);
}

- persistence field bocor ke API
- lazy field bisa trigger query saat serialization
- internal enum bocor ke consumer
- field rename di database menjadi breaking API change
- cyclic reference bisa membuat serialization failure
- sensitive data bisa ikut keluar

public record QuoteResponse(
    String id,
    String status,
    String customerId,
    String currency,
    BigDecimal totalAmount,
    Instant createdAt,
    Instant updatedAt
) {}

@GET
@Path("/{quoteId}")
@Produces(MediaType.APPLICATION_JSON)
public QuoteResponse getQuote(@PathParam("quoteId") String quoteId) {
    Quote quote = quoteService.getQuote(quoteId);
    return quoteMapper.toResponse(quote);
}

Can this response shape remain stable even if database/domain implementation changes?

{
  "id": "Q-1001",
  "status": "DRAFT",
  "customerId": "C-901",
  "currency": "USD",
  "totalAmount": "120.50",
  "createdAt": "2026-07-10T01:30:00Z",
  "updatedAt": "2026-07-10T01:45:00Z"
}

GET /quotes/{quoteId}
GET /orders/{orderId}
GET /catalogs/{catalogId}

{
  "id": "Q-1001",
  "status": "DRAFT",
  "revision": 3
}

{
  "operationId": "op-789",
  "status": "ACCEPTED",
  "statusUrl": "/operations/op-789"
}

POST /quotes
POST /quotes/{quoteId}/submit
POST /orders/{orderId}/cancel

{
  "items": [
    {
      "id": "Q-1001",
      "status": "DRAFT"
    },
    {
      "id": "Q-1002",
      "status": "SUBMITTED"
    }
  ],
  "page": {
    "limit": 50,
    "nextCursor": "eyJpZCI6IlEtMTAwMiJ9",
    "hasMore": true
  }
}

204 No Content  -> operation succeeded, no representation returned
200 []          -> query succeeded and result set is empty
200 {items: []} -> query succeeded with collection envelope

GET /quotes?status=UNKNOWN -> 204
GET /quotes?status=UNKNOWN -> []

Success response shape and error response shape should be intentionally separate.

@GET
@Path("/{id}")
public QuoteResponse getQuote(@PathParam("id") String id) {
    return service.getQuote(id);
}

- simple
- readable
- cocok untuk 200 OK default

- kurang eksplisit untuk status/header
- tidak cocok untuk created/accepted/no-content
- header metadata perlu filter/global logic

@DELETE
@Path("/{id}")
public Response deleteQuote(@PathParam("id") String id) {
    service.deleteQuote(id);
    return Response.noContent().build();
}

- eksplisit status/header/body
- cocok untuk command, file, async, cache, conditional request
- mudah menambahkan Location, ETag, Retry-After, Deprecation

- bisa membuat resource method verbose
- mudah inconsistent jika tidak ada helper/convention

HTTP/1.1 200 OK
Content-Type: application/json
X-Correlation-ID: c-123
ETag: "quote-1001-r3"
Cache-Control: no-store

{
  "items": [],
  "page": {
    "limit": 50,
    "nextCursor": null,
    "hasMore": false
  },
  "meta": {
    "requestId": "r-123",
    "generatedAt": "2026-07-10T01:45:00Z"
  }
}

Protocol metadata belongs in headers.
Application/domain metadata belongs in body.

[
  { "id": "Q-1001" },
  { "id": "Q-1002" }
]

{
  "items": [
    { "id": "Q-1001" },
    { "id": "Q-1002" }
  ],
  "page": {
    "limit": 50,
    "nextCursor": "cursor-abc",
    "hasMore": true
  }
}

- can add page metadata later
- can add links later
- can add warnings later
- can support partial response metadata
- can avoid breaking generated clients

public record PageMetadata(
    Integer limit,
    String nextCursor,
    Boolean hasMore
) {}

public record PageResponse<T>(
    List<T> items,
    PageMetadata page
) {}

@GET
@Produces(MediaType.APPLICATION_JSON)
public PageResponse<QuoteSummaryResponse> listQuotes() {
    return quoteService.listQuotes();
}

List<QuoteSummaryResponse> items = quoteService.listQuotes();
GenericEntity<List<QuoteSummaryResponse>> entity =
    new GenericEntity<List<QuoteSummaryResponse>>(items) {};

return Response.ok(entity).build();

{
  "operationId": "op-123",
  "status": "ACCEPTED",
  "links": {
    "self": "/operations/op-123",
    "quote": "/quotes/Q-1001"
  }
}

{
  "id": "Q-1001",
  "status": "DRAFT",
  "links": {
    "self": "/quotes/Q-1001",
    "submit": "/quotes/Q-1001/submission"
  }
}

- Are links stable across gateway/path changes?
- Are links tenant-aware?
- Are links version-aware?
- Are links absolute or relative?
- Are links authorized per user?

- add optional field
- add nullable field if consumers tolerate unknown fields
- add new enum value only if consumers are designed to tolerate it
- add metadata inside envelope
- add new link relation if ignored by old clients

Adding a field is only compatible if consumers ignore unknown fields.

- rename field
- remove field
- change field type
- change date format
- change number format
- change enum string
- change nullability expectation
- change array to object or object to array
- change semantic meaning of an existing field
- change pagination cursor format without compatibility

- add enum value consumed by switch/case without default
- change ordering semantics in list endpoint
- change default filter behavior
- change precision of money field
- change timezone serialization
- add field that leaks sensitive data
- return empty string instead of null or absent field

What could a strict generated client, dashboard job, ETL process, or downstream validator assume about this response?

{ "discount": null }

{}

{ "discount": "0.00" }

{ "items": [] }

price = null       -> not priced yet?
price = 0          -> free item?
discount = null    -> not evaluated?
discount = 0       -> evaluated, no discount?
effectiveDate null -> always effective? invalid? unknown?

Do not rely on implicit null semantics for business-critical fields.

{
  "pricingStatus": "NOT_CALCULATED",
  "totalAmount": null,
  "currency": "USD"
}

public record QuoteResponse(
    String currency,
    BigDecimal totalAmount
) {}

{
  "currency": "USD",
  "totalAmount": "120.50"
}

{
  "currency": "USD",
  "totalAmount": 120.50
}

{
  "createdAt": "2026-07-10T01:45:00Z"
}

{
  "createdAt": "2026-07-10 08:45:00"
}

{
  "id": "Q-1001"
}

{
  "quoteTablePk": 918273645
}

- Is this DTO transport-specific?
- Does it leak persistence model?
- Does it leak internal enum?
- Does it expose sensitive data?
- Are monetary fields precise?
- Are temporal fields timezone-explicit?
- Are optional fields documented?
- Are enum evolution risks handled?
- Can unknown fields be ignored by consumers?
- Is the shape friendly to generated clients?

public record QuoteSummaryResponse(
    String id,
    String status,
    String customerId,
    String currency,
    BigDecimal totalAmount,
    Instant createdAt,
    Instant updatedAt
) {}

public enum QuoteApiStatus {
    DRAFT,
    SUBMITTED,
    APPROVED,
    REJECTED,
    CANCELLED,
    UNKNOWN
}

{
  "data": {
    "id": "Q-1001"
  },
  "meta": {
    "requestId": "r-123"
  }
}

- consistent metadata placement
- easier pagination/warnings
- easier generated client modeling

- extra nesting everywhere
- awkward for file/stream responses
- not natural for 204 responses
- can conflict with standard error formats

Use envelopes for collections and metadata-rich responses.
Do not force one envelope shape for every endpoint unless platform standard requires it.

@Provider
public class CorrelationResponseFilter implements ContainerResponseFilter {

    @Override
    public void filter(ContainerRequestContext requestContext,
                       ContainerResponseContext responseContext) {
        String correlationId = (String) requestContext.getProperty("correlationId");
        if (correlationId != null) {
            responseContext.getHeaders().putSingle("X-Correlation-ID", correlationId);
        }
    }
}

- correlation ID header
- security headers
- deprecation headers
- server timing headers if standardized
- cache-control defaults if consistent

- business-specific metadata
- endpoint-specific pagination
- domain status
- resource-specific ETag unless filter has correct domain data

- Jackson cannot serialize field
- cyclic reference
- lazy-loaded entity access fails
- date/time serializer missing
- BigDecimal format inconsistent
- stream write fails after partial response
- client disconnects

- service logs say success, client gets 500
- exception stacktrace mentions MessageBodyWriter/ObjectMapper
- response filter logs status 200, but wire response fails
- client receives truncated body

@POST
@Consumes(MediaType.APPLICATION_JSON)
@Produces(MediaType.APPLICATION_JSON)
public Response createQuote(CreateQuoteRequest request,
                            @Context UriInfo uriInfo) {
    QuoteResponse created = quoteService.createQuote(request);

    URI location = uriInfo.getAbsolutePathBuilder()
        .path(created.id())
        .build();

    return Response.created(location)
        .entity(created)
        .build();
}

@DELETE
@Path("/{quoteId}")
public Response deleteQuote(@PathParam("quoteId") String quoteId) {
    quoteService.deleteQuote(quoteId);
    return Response.noContent().build();
}

@POST
@Path("/{quoteId}/price-calculation")
@Produces(MediaType.APPLICATION_JSON)
public Response calculatePrice(@PathParam("quoteId") String quoteId) {
    OperationResponse operation = pricingService.startCalculation(quoteId);

    return Response.accepted(operation)
        .header("Location", "/operations/" + operation.operationId())
        .build();
}

@GET
@Path("/{quoteId}")
@Produces(MediaType.APPLICATION_JSON)
public Response getQuote(@PathParam("quoteId") String quoteId,
                         @Context Request request) {
    QuoteResponse quote = quoteService.getQuote(quoteId);
    EntityTag tag = new EntityTag("quote-" + quote.id() + "-r" + quote.revision());

    Response.ResponseBuilder preconditions = request.evaluatePreconditions(tag);
    if (preconditions != null) {
        return preconditions.tag(tag).build();
    }

    return Response.ok(quote)
        .tag(tag)
        .cacheControl(noStore())
        .build();
}

private CacheControl noStore() {
    CacheControl cc = new CacheControl();
    cc.setNoStore(true);
    return cc;
}

- add/remove headers
- terminate TLS
- compress response
- enforce max body size
- rewrite Location header
- convert upstream 5xx to platform error shape
- add CORS headers
- strip internal headers
- timeout before service completes

Compare application logs, service-level response, gateway logs, and client-observed response.

@Test
void getQuoteReturnsStableResponseShape() {
    Response response = target("/quotes/Q-1001")
        .request(MediaType.APPLICATION_JSON)
        .get();

    assertEquals(200, response.getStatus());

    JsonNode body = objectMapper.readTree(response.readEntity(String.class));
    assertEquals("Q-1001", body.get("id").asText());
    assertTrue(body.has("status"));
    assertFalse(body.has("internalCostBasis"));
}

- compare OpenAPI diff
- run generated client against endpoint
- verify unknown-field tolerance
- verify enum evolution handling
- verify date/time format
- verify null/missing semantics

- response field names
- nested structure
- date/time format
- error envelope shape

- volatile IDs
- exact timestamp generated at runtime
- unordered object/map field order

1. Confirm the raw response as seen by the client.
2. Confirm status, headers, and body separately.
3. Check resource method return path.
4. Check mapper from domain/entity to DTO.
5. Check MessageBodyWriter/ObjectMapper/JSON-B config.
6. Check response filters.
7. Check gateway/proxy mutation.
8. Check generated OpenAPI/client expectation.
9. Check whether recent change was additive or breaking.
10. Check consumer logs for parse/semantic failure.

- Is the response wrong at service boundary or after gateway?
- Did serialization alter field names or date format?
- Is a null field intentionally null or accidentally missing data?
- Did a DTO change bypass contract review?
- Did pagination require stable sort but query does not enforce it?

- Is the status code correct?
- Is the response body shape intentional?
- Is the DTO separate from domain/entity/persistence model?
- Are sensitive fields excluded?
- Are monetary and temporal fields represented safely?
- Are null/missing/empty semantics clear?
- Is pagination metadata present for collection endpoints?
- Is the change backward-compatible?
- Are enum changes consumer-safe?
- Is OpenAPI updated?
- Are generated clients impacted?
- Are response filters relied on implicitly?
- Are gateway/proxy headers considered?
- Are tests verifying status, headers, and body?

- returning JPA/MyBatis persistence entity directly
- adding internal debug field to response
- changing field name without version/deprecation
- changing list ordering without documenting it
- using `double` for money
- returning local date-time without timezone for instant-like fields
- using 204 for empty search result inconsistently

- What is the standard response envelope, if any?
- Are resource methods expected to return DTO directly or `Response`?
- Is there a common response builder/helper?
- Is there a common pagination response model?
- Are response DTOs generated from OpenAPI or hand-written?
- Are generated clients used by internal teams?
- What JSON provider is active: Jackson, JSON-B, Jersey default, custom?
- Are ObjectMapper/JSON-B settings centralized?
- What is the date/time serialization convention?
- What is the monetary serialization convention?
- Are unknown fields tolerated by consumers?
- How are enum changes governed?
- Is there an API compatibility matrix?
- Is OpenAPI diff checked in CI?
- Does gateway mutate response headers/body?
- Are correlation/security/deprecation headers injected by filters or gateway?
- Is ETag/cache-control used anywhere?
- Are response snapshots or contract tests used?
- What fields are classified as sensitive/PII?

- Response model is a public contract, not an internal object dump.
- DTO boundary protects consumers from implementation churn.
- Metadata must be deliberate: headers for protocol, body for application/domain.
- Empty, null, missing, and zero have different meanings.
- Compatibility is about consumer assumptions, not only schema syntax.
- Serialization is part of runtime behavior and can fail after service logic succeeds.
- Gateway/proxy behavior can change the final response.
- Senior PR review must treat response changes as contract changes.