REST API 기본 및 모범 사례 설명

RESTful API는 표준 HTTP 메서드를 사용하여 시스템의 서로 다른 부분들이 서로 통신할 수 있게 해준다. 오늘날 개발자들이 API를 구축하고 사용하는 가장 일반적인 방법으로, 모바일 앱부터 백엔드 마이크로서비스까지 모든 것을 지원한다.

이 글에서는 API를 사용하고 유지 관리하기 어렵게 만드는 혼란스럽고 일관성 없는 패턴을 피하면서, 입증된 모범 사례를 따라 깔끔하고 일관된 REST API를 설계하는 방법을 설명한다.

 

1. 리소스 모델링: REST의 기초

REST에서는 모든 것이 리소스다 — 제품, 사용자, 리뷰 등. 이러한 리소스는 동사가 아닌 명사를 사용하여 URL을 통해 노출된다:

• ✅ GET /products
• ❌ GET /getAllProducts

리소스는 개별 항목이거나 컬렉션일 수 있다:

• 컬렉션: /api/v1/products
• 단일 항목: /api/v1/products/123
• 중첩 리소스: /api/v1/products/123/reviews

명확하고 일관된 URL 설계는 API를 예측 가능하게 만들어, 이를 사용하는 개발자들에게 큰 장점을 제공한다.

---

2. 필터링, 정렬 및 페이지네이션

실제 API는 대량의 데이터셋을 반환한다. 클라이언트(와 서버)를 과부하시키지 않기 위해 필터링, 정렬, 페이지네이션을 지원해야 한다.

필터링

클라이언트가 결과 집합을 좁힐 수 있도록 해준다:

GET /products?category=books&inStock=true

정렬

클라이언트가 순서를 제어할 수 있도록 해준다:

GET /products?sort=price_asc
GET /products?sort=rating_desc

페이지네이션

대량의 데이터셋을 페이지로 나눈다:

GET /products?page=2&limit=20

페이지네이션은 일반적으로 page와 limit 쿼리 파라미터로 관리된다. 하지만 다른 스타일도 있다:

• 오프셋 기반: ?offset=40&limit=20
• 커서 기반: ?after=xyz123

이러한 도구들은 성능을 개선하고, 대역폭을 줄이며, 프론트엔드 팀(및 다른 서비스)에 더 많은 제어권을 제공한다.

---

3. HTTP 메서드: CRUD에 매핑

REST는 기본 작업을 위해 표준 HTTP 메서드를 사용한다:

예시:

• GET /products/123 — 제품 가져오기
• POST /products — 새 제품 생성
• PATCH /products/123 — 가격 업데이트
• DELETE /products/123 — 제품 삭제

---

4. 상태 코드 및 오류 처리

API는 웹의 언어를 사용해야 하며, 이는 적절한 HTTP 상태 코드를 반환해야 함을 의미한다.

일반적인 상태 코드

• 200 OK — 성공
• 201 Created — 리소스 생성
• 204 No Content — 성공, 반환할 내용 없음
• 400 Bad Request — 잘못된 입력
• 401 Unauthorized — 사용자 인증되지 않음
• 404 Not Found — 리소스 존재하지 않음
• 500 Internal Server Error — 서버 오류

표준 오류 응답

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "잘못된 제품 ID 형식",
    "details": [...]
  }
}

일관성을 유지하라. 클라이언트는 무엇이 잘못되었는지 추측하지 않아야 한다.

---

5. RESTful API 설계 모범 사례

API 설계를 향상시키기 위한 체크리스트는 다음과 같다:

• ✅ 리소스 이름에 복수 명사를 사용하라 (/products)
• ✅ URL을 일관되고 계층적으로 유지하라
• ✅ 필터링, 정렬, 페이지네이션을 지원하라
• ✅ 필요할 때 콘텐츠 협상(Content Negotiation)을 사용하라 (Accept: application/json)
• ✅ API에 버전을 추가하라 (/v1/users)
• ✅ 탐색 가능성을 위해 HATEOAS 링크를 포함하라 (선택 사항이지만 유용)

나쁜 API 설계는 혼란, 일관성 없는 구현, 그리고 장기적인 문제를 초래한다. 좋은 설계는 시간을 절약하고 제품과 함께 확장된다.

---

요약

훌륭한 RESTful API 설계에 대한 핵심 구성 요소를 다루었다

요약하면.

• 리소스 모델링과 깔끔한 URL 설계
• 필터링, 정렬, 페이지네이션 기법
• HTTP 메서드의 적절한 사용
• 의미 있는 상태 코드와 일관된 오류 응답
• 확장 가능하고 직관적인 API를 위한 모범 사례