REST API 서버 개발 시 주의해야 할 사항

 

1. 기본 설계 원칙

• 리소스 중심 설계
  • 동사보다는 명사 사용 ( 예: ✅ /users, ❌ /getUsers )
  • 계층적 구조 (예: /users/{id}/orders)
• 적절한 HTTP 메서드 사용

GET /users       # 조회
POST /users      # 생성
PUT /users/{id}  # 전체 수정
PATCH /users/{id}# 부분 수정
DELETE /users/{id}# 삭제

 

 

 

2. 엔드포인트 네이밍 규칙

• 일관성 유지
  • 소문자 사용 ( ✅ /orders, ❌ /Orders )
  • 하이픈(-) 사용 가능, 밑줄(_) 피하기
  • 복수형 권장 ( ✅ /products,  ❌ /product )
• 예시: 좋은 vs 나쁜 사례

✅ /users/{id}/orders
❌ /getUserOrderById

 

 

 

3. 버전 관리 전략

• URL 경로 방식

/v1/users
/v2/users

• 헤더 방식

GET /users
Accept: application/vnd.company.api.v1+json

 

  - 헤더방식으로 사용하는 곳도 있나? 싶다.

 

 

 

 

4. 응답 처리 표준화

• 공통 응답 포맷

{
  "status": "success",
  "data": { ... },
  "error": null,
  "meta": { /* 페이징 정보 등 */ }
}

 

• HTTP 상태 코드 정확 사용
  • 200 OK: 일반 성공
  • 201 Created: 리소스 생성 성공
  • 400 Bad Request: 클라이언트 오류
  • 401 Unauthorized: 인증 실패
  • 404 Not Found: 리소스 없음
  • 429 Too Many Requests: 요청 과다

 

 

5. 보안 고려사항

• 인증/인가
  • JWT, OAuth 2.0 구현
  • 모든 엔드포인트에 인증 적용 (공개 API 제외)
• 보안 헤더

Strict-Transport-Security: max-age=63072000
X-Content-Type-Options: nosniff
X-Frame-Options: DENY

 

 

 

6. 기타

• 멱등성 보장 
  • PUT, DELETE 메서드는 반복 실행 시 동일 결과
• CORS
  • 프론트엔드에서 호출 시 Access-Control-Allow-Origin 관리