A JAX-RS resource method is not just Java code; it is a public operational contract.

1. API contract
2. application behavior
3. runtime/operational behavior
4. consumer compatibility

- Is this API semantically correct?
- Is this change backward-compatible?
- Can consumers understand and handle all outcomes?
- Can operators debug it at 03:00?
- Can this endpoint survive retries, duplicates, timeouts, and partial failure?
- Does it enforce identity, authorization, and tenant isolation?
- Does it hide internal implementation details from public contract?

GET     -> read only, safe, no mutation
POST    -> create, command, non-idempotent operation unless explicitly designed
PUT     -> replace/upsert resource, idempotent by design
PATCH   -> partial update, semantics must be documented
DELETE  -> delete/cancel/remove, should be idempotent where possible

[ ] Does GET avoid mutation and side effects?
[ ] Is POST used for command-like operation?
[ ] Is PUT idempotent?
[ ] Is PATCH patch format clear?
[ ] Is DELETE behavior clear when resource already absent?
[ ] Does retry behavior match method semantics?

- GET triggers calculation, workflow transition, or database mutation
- POST used for simple read because query is complex
- DELETE returns random errors when resource already deleted
- PUT behaves like partial update but is undocumented
- endpoint requires client to know internal workflow state

- nouns not verbs for stable resources
- command endpoints are explicit when needed
- hierarchy represents ownership only when real
- IDs are opaque
- internal table names are not exposed
- URI does not leak implementation module names

[ ] Is the resource name stable from business/API perspective?
[ ] Does URI avoid internal class/table/process names?
[ ] Are path parameters meaningful and bounded?
[ ] Is nested path justified by ownership or scoping?
[ ] Is command/action modeled clearly?
[ ] Is versioning approach consistent?

GET /quotes/{quoteId}
POST /quotes/{quoteId}/submit
GET /orders/{orderId}/status
GET /catalog-items?effectiveDate=2026-07-10

POST /quoteService/calculateQuoteImpl
GET /db/quote_header/{id}
POST /workflow/task/completeInternalNode42

[ ] Are required fields truly required?
[ ] Are optional fields defaulted safely?
[ ] Are unknown fields handled intentionally?
[ ] Are field names stable and consistent?
[ ] Are enum values backward-compatible?
[ ] Are date/time fields timezone-explicit?
[ ] Are monetary values represented with decimal precision?
[ ] Are arrays bounded?
[ ] Are strings length-limited?
[ ] Are IDs opaque and validated?
[ ] Are headers documented?
[ ] Are query parameters bounded and indexed if they hit DB?

public Response createQuote(QuoteEntity entity) { ... }

public Response createQuote(CreateQuoteRequest request) { ... }

[ ] Is success response shape documented?
[ ] Is empty response intentional?
[ ] Is metadata included where needed?
[ ] Are IDs opaque?
[ ] Are timestamps serialized consistently?
[ ] Are monetary values precise?
[ ] Are enum values stable?
[ ] Are nulls handled consistently?
[ ] Are internal fields hidden?
[ ] Is pagination metadata present for list responses?
[ ] Are links/cursors stable if used?

Usually compatible:
- adding optional response field
- adding optional enum only if consumers are tolerant
- adding new endpoint
- adding optional query parameter

Usually breaking:
- removing field
- renaming field
- changing type
- changing nullability from nullable to required or reverse depending contract
- changing status code expected by clients
- changing error code/shape
- changing enum behavior without consumer tolerance

[ ] Does success status match operation?
[ ] Does create return 201 when appropriate?
[ ] Does async command return 202 when result is not ready?
[ ] Does validation failure return 400 or agreed equivalent?
[ ] Does auth failure distinguish 401 vs 403 correctly?
[ ] Does not-found avoid leaking unauthorized resource existence?
[ ] Does conflict use 409 where state conflict exists?
[ ] Does rate limiting use 429 if platform standard allows?
[ ] Does retryable failure include proper retry guidance?

[ ] Is Content-Type explicit for request/response with body?
[ ] Is Accept behavior defined?
[ ] Is Location returned for created resource if convention requires?
[ ] Is Retry-After returned for throttling or long polling timeout?
[ ] Is ETag used for cache/conditional update where appropriate?
[ ] Are correlation/request IDs propagated?
[ ] Are deprecation/sunset headers used if API is being retired?
[ ] Are security headers handled by app or gateway?
[ ] Are sensitive headers excluded from logs?

[ ] Are DTO constraints explicit?
[ ] Are nested objects validated?
[ ] Are cross-field rules handled?
[ ] Are collection sizes bounded?
[ ] Are string lengths bounded?
[ ] Are dates checked for valid windows?
[ ] Are monetary values checked for scale/precision?
[ ] Are tenant/customer IDs validated against auth context?
[ ] Are validation errors mapped to stable error codes?
[ ] Are validation messages safe and not leaking internals?

API validation      -> request shape and basic constraints
Domain validation   -> business invariants
Persistence guard   -> database constraints as final protection

[ ] Is error shape standard?
[ ] Is error code stable?
[ ] Is user-facing message safe?
[ ] Is developer/debug detail gated or omitted?
[ ] Is correlation ID included or retrievable?
[ ] Are validation field errors structured?
[ ] Is retryability clear?
[ ] Is downstream failure mapped intentionally?
[ ] Are domain conflicts distinguishable from technical failures?

{
  "errorCode": "QUOTE_STATE_CONFLICT",
  "message": "Quote cannot be submitted from the current state.",
  "correlationId": "req-abc-123",
  "details": [
    {
      "field": "quoteId",
      "reason": "invalid_state"
    }
  ]
}

{
  "error": "java.lang.NullPointerException at QuoteService.java:42"
}

Who is calling? What are they allowed to do? Which tenant/data scope applies?

[ ] Is authentication required?
[ ] Is anonymous access intentional?
[ ] Is authorization checked at resource/object level?
[ ] Is tenant context derived from trusted identity, not raw request input?
[ ] Are service-to-service calls authenticated?
[ ] Are scopes/roles/permissions sufficient and minimal?
[ ] Are sensitive fields masked in response?
[ ] Are secrets never returned or logged?
[ ] Are file uploads scanned/limited if applicable?
[ ] Are audit events emitted for sensitive actions?

- only checking user is logged in, not permission
- trusting tenantId from path without comparing auth context
- admin-only endpoint hidden by URL naming but not protected
- WebSocket/SSE endpoint bypasses normal security filters
- error response leaks existence of unauthorized resource

[ ] Is tenant resolved from trusted context?
[ ] Is tenant applied to every data access path?
[ ] Is tenant included in downstream requests/events where required?
[ ] Is tenant-specific config/catalog/pricing/rule applied?
[ ] Are logs tenant-aware but not high-cardinality in metrics?
[ ] Are caches keyed by tenant where needed?
[ ] Are idempotency keys tenant-scoped?
[ ] Are tests covering cross-tenant denial?

cache key = quoteId

cache key = tenantId + quoteId

[ ] Is operation safe to retry?
[ ] If not naturally idempotent, is idempotency key required?
[ ] Is idempotency key scoped by tenant/user/operation?
[ ] Is duplicate request behavior documented?
[ ] Is conflict response stable?
[ ] Are downstream calls protected from duplicate effects?
[ ] Are database writes transactionally safe?
[ ] Are events published exactly once or at least safely duplicated?

What happens if the server succeeds but the client times out before receiving the response?

[ ] Is transaction boundary explicit?
[ ] Are multiple writes atomic where required?
[ ] Are external calls inside DB transaction avoided or justified?
[ ] Are locks used safely?
[ ] Is isolation level sufficient?
[ ] Is optimistic locking needed?
[ ] Is duplicate command guarded?
[ ] Is outbox/inbox needed for event consistency?
[ ] Is migration compatible with old and new app versions?

DB transaction open while calling downstream HTTP service.

- long lock hold
- pool exhaustion
- deadlocks
- poor failure recovery
- unknown partial side effects

[ ] Is database query indexed?
[ ] Are pagination limits enforced?
[ ] Is N+1 query avoided?
[ ] Is response payload bounded?
[ ] Is file/streaming endpoint avoiding full memory buffering?
[ ] Are expensive operations asynchronous or cached where appropriate?
[ ] Are downstream calls bounded by timeout?
[ ] Is connection pool impact understood?
[ ] Is p95/p99 latency expectation clear?

[ ] Is sorting field indexed or restricted?
[ ] Is filtering grammar bounded?
[ ] Is max page size enforced?
[ ] Is cursor stable under concurrent writes?
[ ] Is total count query avoided or optimized?

[ ] Are inbound and outbound timeouts defined?
[ ] Is retry policy explicit and bounded?
[ ] Is retry budget respected?
[ ] Is circuit breaker needed?
[ ] Is bulkhead needed?
[ ] Is fallback safe and honest?
[ ] Is graceful degradation possible?
[ ] Is rate limiting enforced at gateway or app layer?
[ ] Is load shedding behavior defined?
[ ] Are retry storm and thundering herd risks considered?

A fallback that returns stale or partial data must be explicit in contract or internal semantics.

[ ] Is request logged at appropriate level?
[ ] Is correlation ID present and propagated?
[ ] Is causation ID/event ID captured where relevant?
[ ] Are metrics emitted for count, latency, error, saturation?
[ ] Is tracing instrumented across DB/HTTP/Kafka boundaries?
[ ] Are important domain transitions auditable?
[ ] Are high-cardinality labels avoided?
[ ] Are sensitive fields redacted?
[ ] Is dashboard/alert impact considered for critical endpoint?

- request count
- latency histogram
- error count by stable category
- dependency latency/error where relevant
- saturation for queue/thread/connection pool where relevant

quoteId, orderId, userId, raw tenantId, customerName, email

[ ] Is max upload/download size enforced?
[ ] Is content type validated?
[ ] Is file name sanitized?
[ ] Is stream copied with bounded buffer?
[ ] Is payload not fully loaded into heap?
[ ] Is temp file behavior understood?
[ ] Is virus/malware scanning required?
[ ] Is checksum required?
[ ] Is partial failure handled?
[ ] Are gateway/proxy body limits verified?
[ ] Are timeout and cancellation handled?

byte[] file = inputStream.readAllBytes();

[ ] Does endpoint return 202 Accepted when appropriate?
[ ] Is status endpoint provided?
[ ] Is operation ID returned?
[ ] Is cancellation supported or explicitly not supported?
[ ] Is duplicate command handled?
[ ] Are background job failures visible?
[ ] Is event publication reliable?
[ ] Is reconciliation available for partial failure?
[ ] Is UI notification separate from source of truth?

POST /quotes/{quoteId}/calculation-jobs
→ 202 Accepted
Location: /quotes/{quoteId}/calculation-jobs/{jobId}

GET /quotes/{quoteId}/calculation-jobs/{jobId}

[ ] Is OpenAPI updated?
[ ] Does implementation match OpenAPI?
[ ] Are examples updated?
[ ] Are error responses documented?
[ ] Are auth requirements documented?
[ ] Are pagination/filtering/sorting documented?
[ ] Does API lint pass?
[ ] Does generated client still compile?
[ ] Does generated server stub or annotation mapping stay aligned?
[ ] Does compatibility diff show no unintended breaking change?

- endpoint exists but not documented
- OpenAPI documents field that code never returns
- generated client breaks after field rename
- API lint warnings ignored until consumers complain

[ ] Can old client call new server?
[ ] Can new client call old server?
[ ] Can old server read data written by new server?
[ ] Can new server read data written by old server?
[ ] Can both versions publish/consume events safely?
[ ] Is database migration expand-contract?
[ ] Is feature flag needed to separate deploy from release?

1. expand database/schema/API to support both versions
2. deploy code that can read old and new shape
3. enable feature flag gradually
4. migrate/backfill data if needed
5. verify consumers
6. contract old field/path only after deprecation window

[ ] Unit test for domain/service behavior
[ ] Resource/endpoint test for HTTP mapping
[ ] Validation failure test
[ ] Authorization negative test
[ ] Tenant isolation negative test
[ ] Error mapper test
[ ] Serialization/deserialization test
[ ] Contract/OpenAPI test
[ ] Integration test with DB if query/write involved
[ ] Kafka/event test if event published
[ ] Idempotency/duplicate test for commands
[ ] Timeout/failure test for downstream dependency

Which production failure would this test suite catch?

[ ] Is endpoint discoverable?
[ ] Are examples realistic?
[ ] Are error cases documented?
[ ] Are headers documented?
[ ] Are pagination/filter/sort examples included?
[ ] Are auth scopes/permissions documented?
[ ] Is deprecation notice clear if applicable?
[ ] Are operational notes included for async/streaming endpoints?

- Is there an internal API style guide?
- Is OpenAPI source-of-truth or generated artifact?
- Is API lint enforced in CI?
- Is breaking change detection automated?
- Is there an API review board/process?
- Are generated clients used by other services or teams?

- Is endpoint JAX-RS standard only or Jersey-specific?
- Are custom filters/interceptors involved?
- Which ExceptionMapper handles failures?
- Which JSON provider serializes DTOs?
- Are Servlet filters/gateway policies modifying request/response?

- What auth mechanism protects endpoint?
- Where is authorization enforced?
- How is tenant resolved?
- Is tenant applied to data access and cache keys?
- Is audit logging required?

- What is expected latency?
- What dependencies are called?
- Are timeout/retry/circuit breaker policies standard?
- Are metrics/logs/traces available?
- Does dashboard/alert need update?

- Who consumes this endpoint?
- Is there a compatibility matrix?
- Is deprecation policy followed?
- Does rolling deploy remain safe?
- Does database migration preserve old/new compatibility?

Approve:
- semantics correct
- compatible
- secure
- observable
- tested
- operationally bounded

Request changes:
- unclear contract
- missing auth/tenant check
- unbounded payload/query
- weak error mapping
- missing tests for core risk
- hidden breaking change

Block:
- data leak risk
- cross-tenant risk
- unsafe migration
- critical endpoint without rollback path
- retry/idempotency bug causing duplicate business action
- severe production failure mode ignored

This POST command is not idempotent. What happens if the client times out after the DB commit but before receiving the response? Please add an idempotency key or document why duplicate command is impossible.

Maybe handle errors better.

HTTP
[ ] method semantics correct
[ ] status codes consistent
[ ] headers intentional
[ ] content negotiation clear
[ ] pagination/filtering bounded

Contract
[ ] OpenAPI updated
[ ] no unintended breaking change
[ ] error shape stable
[ ] response shape stable
[ ] generated client/server impact checked

Validation
[ ] DTO validation present
[ ] domain invariants enforced
[ ] invalid input returns stable error
[ ] length/size/collection bounds enforced

Security
[ ] authentication required where needed
[ ] authorization object-level
[ ] tenant isolation enforced
[ ] sensitive data redacted
[ ] audit where required

Resilience
[ ] timeout defined
[ ] retry/idempotency safe
[ ] downstream failure mapped
[ ] rate/load protection considered
[ ] async/streaming bounded

Data
[ ] transaction boundary safe
[ ] DB query indexed/bounded
[ ] migration compatible
[ ] event/outbox consistency if needed

Observability
[ ] logs useful and safe
[ ] metrics added
[ ] trace propagation preserved
[ ] correlation ID propagated

Tests
[ ] happy path
[ ] validation failure
[ ] auth/tenant failure
[ ] dependency failure
[ ] compatibility/contract

POST /quotes/{quoteId}/submit

- Is submit a command? Yes, POST is reasonable.
- Can submit be retried? Need idempotency or state conflict behavior.
- What if quote already submitted? 200/204 idempotent success or 409 conflict?
- Is user allowed to submit this quote?
- Is quote tenant checked against auth context?
- Is quote in valid state?
- Are pricing/catalog effective dates locked?
- Does submit publish event?
- Is event publication transactional via outbox?
- What does client receive on validation/domain conflict?
- Is audit log emitted?
- Is OpenAPI updated?
- Are tests covering duplicate submit, wrong tenant, invalid state, and event publication?

- resource method returns entity directly from database
- endpoint accepts persistence entity as request body
- GET mutates state
- POST command has no idempotency story
- endpoint has no authorization beyond authentication
- tenantId from path is trusted blindly
- list endpoint has no max limit
- filtering supports arbitrary unindexed fields
- error response leaks stack trace
- downstream timeout defaults are unknown
- OpenAPI is not updated
- no negative tests
- API change is compatible only when all services deploy at exactly the same time

- Endpoint review is contract review, not just Java code review.
- HTTP semantics affect retry, caching, compatibility, and operational behavior.
- Backward compatibility must be checked for clients, rolling deploys, DB, and events.
- Security review must include object-level authorization and tenant isolation.
- Observability must be designed before incident happens.
- Idempotency and timeout behavior are mandatory for command endpoints.
- A good PR review explains the production failure it prevents.