daithanh-hua/java-rest-api-design icon
public
Published on 5/17/2025
Java REST API Design

REST API Design Rule (Java context)

Rules

When designing and implementing RESTful APIs in Java (typically with Spring MVC):

  1. HTTP Verbs: Use appropriate HTTP verbs (GET for retrieval, POST for creation, PUT for update/replace, PATCH for partial update, DELETE for removal).
  2. Status Codes: Return correct HTTP status codes (e.g., 200 OK, 201 Created, 204 No Content, 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, 500 Internal Server Error).
  3. Resource Naming: Use nouns for resource URIs (e.g., /users, /orders/{orderId}).
  4. DTOs: Use separate DTOs for request and response payloads. Validate request DTOs using Bean Validation (javax.validation or jakarta.validation).
  5. Versioning: Suggest API versioning strategy (e.g., URI path /api/v1/..., or via custom headers).
  6. Content Negotiation: Support JSON (application/json) by default.