Java API Endpoints

Scope And Existing Contracts

Inspect the project's Java/Spring versions, endpoint contract, architecture, serializer, persistence and error handling before editing. Preserve published compatibility and explicit project choices; do not install another framework or migrate unrelated endpoints to apply this skill.

Classify the endpoint as a REST resource operation, rendered page, traditional HTML form action, or another capability action. POST, JSON, or JavaScript submission alone does not establish resource creation. A rendered form calling REST still follows the REST contract at its submission endpoint.

When implementing a resource endpoint, read the worked User endpoint. It shows a preferred flow, not a mandatory class count, authentication product, or architecture activation.

Responsibilities And Naming

• For ordinary resource operations, prefer Controller -> Service -> Repository. Controllers consume typed validated input, invoke application work, and handle HTTP adaptation through existing infrastructure. Keep persistence coordination and business rules out of controllers.
• Keep resource vocabulary consistent: UserController, UserService, CreateUserRequest, and an output-only UserDto or established UserResponse. For new or intentionally redesigned routes, prefer plural resource nouns such as POST /api/users and GET /api/users/{userId}. Use /registrations only when registration itself is the resource.
• Follow existing Java controller naming, including the verb/resource convention in active java-ddd-architecture. Name supported resource service operations create, read, update, and delete where these accurately describe them; preserve meaningful domain operations and explicit project conventions. Do not force a business workflow into generic CRUD or generate unused operations.
• Separate request and output contracts. Explicitly select public output fields; do not serialize an entity wholesale, echo submitted input, or leak credentials or infrastructure types.
• Services coordinate construction, business-state decisions, persistence, and application output mapping. Use focused factories under java-readable-code when justified. A mapper or constructor already owned by the project does not require a new factory layer merely to match the example.
• Domain repositories consume/return their domain model and hide technical transport types. Preserve established projection/query-service contracts when the operation is a read model rather than aggregate retrieval.
• Use java-request-validation for binding, validation and input DTO ownership. Map transport DTOs to application input when contracts differ; do not require redundant copies of an intentionally shared application-owned type.