API Design Standards

27.1. RESTful API Rules

27.1.1. URL Naming

• Only lowercase letters and hyphens (-) must be used. Underscores (_) and camelCase must not be used.
• Resource names must use plural forms.
• URLs must not end with a trailing slash (/).

Category	Correct Example	Incorrect Example
Plural	/api/users	/api/user
Hyphen	/api/user-profiles	/api/user_profiles
Lowercase	/api/users	/api/Users

27.1.2. HTTP Methods

Method	Purpose	Example	Response Code
GET	Retrieve resource	GET /api/users	200
POST	Create resource	POST /api/users	201
PUT	Full resource update	PUT /api/users/1	200
PATCH	Partial resource update	PATCH /api/users/1	200
DELETE	Delete resource	DELETE /api/users/1	204

27.1.3. URL Hierarchy

Relationships between resources must be expressed through URL paths.

GET /api/users/{userId}/orders          # List orders for a specific user
GET /api/users/{userId}/orders/{orderId}  # Specific order for a specific user

• Nesting is permitted up to 2 levels only.
• If nesting beyond 3 levels is required, query parameters must be used.

---

27.2. Request/Response Format

27.2.1. Standard Response Structure

Single resource response:

{
  "id": 1,
  "name": "John Doe",
  "email": "user@tienipia.com",
  "createdAt": "2026-02-28T10:30:00"
}

27.2.2. List Response (Pagination)

{
  "content": [
    {
      "id": 1,
      "name": "John Doe",
      "email": "user@tienipia.com"
    }
  ],
  "page": 0,
  "size": 20,
  "totalElements": 150,
  "totalPages": 8
}

27.2.3. Pagination Parameters

Parameter	Description	Default
page	Page number (starts from 0)	0
size	Page size	20
sort	Sort criteria	Default sort when unspecified

GET /api/users?page=0&size=20&sort=createdAt,desc

27.2.4. Date/Time Format

• The ISO 8601 format must be used: 2026-02-28T10:30:00
• When a timezone is required: 2026-02-28T10:30:00+09:00

---

27.3. Error Code System

27.3.1. HTTP Status Codes

Code	Meaning	Usage Criteria
200	OK	Successful retrieval or update
201	Created	Successful resource creation
204	No Content	Successful deletion
400	Bad Request	Input validation failure
401	Unauthorized	Authentication required
403	Forbidden	Insufficient permissions
404	Not Found	Resource does not exist
409	Conflict	Resource conflict (e.g., duplicate)
500	Internal Server Error	Internal server error

27.3.2. Custom Error Codes

Custom error codes must be used in addition to HTTP status codes to differentiate specific errors.

{prefix}{sequence}

Prefix	Domain	Example
C	Common	C001 (invalid input)
U	User	U001 (user not found)
A	Authentication	A001 (token expired)
O	Order	O001 (order not found)

27.3.3. Standard Error Response Format

{
  "code": "U001",
  "message": "User not found.",
  "timestamp": "2026-02-28T10:30:00"
}

For input validation errors, field-level details must be included.

{
  "code": "C001",
  "message": "Invalid input values.",
  "timestamp": "2026-02-28T10:30:00",
  "errors": [
    {
      "field": "email",
      "value": "invalid-email",
      "reason": "Invalid email format."
    }
  ]
}

---

27.4. API Documentation

27.4.1. SpringDoc Implementation

All API projects must implement SpringDoc (OpenAPI 3.0) to provide Swagger UI.

<dependency>
  <groupId>org.springdoc</groupId>
  <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
  <version>2.8.4</version>
</dependency>

# application.yml
springdoc:
  swagger-ui:
    path: /swagger-ui.html
  api-docs:
    path: /v3/api-docs

27.4.2. API Annotations

OpenAPI annotations must be applied to Controllers and DTOs.

@RestController
@RequestMapping("/api/users")
@Tag(name = "Users", description = "User management API")
public class UserController {

  @Operation(summary = "Get user", description = "Retrieves a user by ID.")
  @ApiResponses({
      @ApiResponse(responseCode = "200", description = "Successfully retrieved"),
      @ApiResponse(responseCode = "404", description = "User not found")
  })
  @GetMapping("/{id}")
  public ResponseEntity<UserResponse> getUser(@PathVariable Long id) {
    return ResponseEntity.ok(userService.findById(id));
  }
}

27.4.3. Documentation Principles

• All public APIs must include the @Operation annotation.
• Request/response DTOs must include field descriptions.
• Swagger UI must be enabled only in development/staging environments and disabled in production.