Java Api Design Rest

• Business capability and use-cases (what users do, not just fields).
• Existing API patterns in the repo (if any).
• Data model constraints (IDs, uniqueness, relationships).
• Non-functional constraints: latency, payload limits, caching, consistency.

Procedure (contract-first)

1. Model resources

   • Identify primary resources (nouns) and stable identifiers.
   • Define sub-resources and relationships only when they have clear ownership.
   • Decide representation: full vs summary vs expandable fields.

2. Define endpoints + semantics

   • GET collection/item, POST create, PUT replace, PATCH partial update, DELETE.
   • Ensure idempotency requirements are explicit (especially POST).
   • Choose status codes intentionally.

3. Pagination and filtering

   • Choose a pagination strategy:
     • Cursor/token-based for large mutable collections (recommended).
     • Offset-based only when stable ordering and costs are acceptable.
   • Define request params and response shape (including next token).
   • Ensure sorting/filtering are consistent across pages.

4. Error model (Problem Details)

   • Standardize error responses with fields:
     • type, title, status, detail, instance
   • Define stable error codes and a mapping table from exceptions to problem types.

5. Versioning & compatibility

   • Prefer backward-compatible changes.
   • Define a versioning strategy (path/header/media-type) and rules for breaking changes.

6. Produce OpenAPI draft

   • Write OpenAPI paths, schemas, responses (including error responses).
   • Include examples and common error cases.

7. Define implementation contracts

   • Define controller signatures (request/response DTOs).
   • Define service layer contracts (business interfaces).
   • Add minimal tests or contract checks if required.

Outputs / Artifacts

• OpenAPI draft (YAML/JSON) with:
  • endpoints, schemas, pagination, errors
• Controller/service contracts (interfaces or skeletons)
• A short API change note:
  • breaking changes? migration?

Definition of Done (DoD)

• Resources and endpoints follow a consistent naming scheme.
• Pagination strategy is documented and implemented in OpenAPI.
• Error model is standardized and includes machine-readable fields.
• OpenAPI draft validates structurally (basic sanity).
• Example requests/responses exist for happy path + common errors.

Guardrails

• Do not leak internal exceptions/stack traces to clients.
• Do not introduce breaking changes without versioning/migration plan.
• Do not use ad-hoc pagination shapes; keep it consistent across endpoints.
• Require explicit confirmation for non-idempotent operations.

Common failure modes & fixes

• Endpoint becomes "action soup" (/doThing) → refactor into resource modeling.
• Pagination breaks with filtering/sorting → ensure stable ordering and token binding.
• Errors inconsistent → enforce Problem Details and a shared error registry.

References

• Use templates/openapi/ for starter OAS files.
• Use templates/errors/ for Problem Details examples.
• Use references/ for detailed REST checklists and versioning guidance.