REST API 완벽 가이드: 기본 개념부터 모범 사례까지

 

안녕하세요! 오늘은 웹 개발의 핵심, REST API에 대해 깊이 있게 파헤쳐 보겠습니다. 개발자라면 누구나 알아야 할 필수 지식, REST API의 기본 개념부터 실제 현업에서 유용하게 쓰이는 모범 사례까지, 이 글 하나로 완벽하게 정리해 드리겠습니다. [00:00]

REST API란 무엇일까요?

REST(Representational State Transfer) API는 웹의 기존 기술과 HTTP 프로토콜을 그대로 활용하여, 시스템의 여러 구성 요소가 서로 원활하게 통신할 수 있도록 하는 아키텍처 스타일입니다. [00:00] 오늘날 개발자들이 API를 구축하고 사용하는 가장 보편적인 방식으로, 웹 생태계의 근간을 이루고 있다고 해도 과언이 아닙니다. [00:07]

REST API의 핵심 원칙과 제약 조건

1. 리소스 중심의 URL 설계

REST의 가장 중요한 개념은 바로 '리소스(Resource)'입니다. [00:46] 제품, 주문, 리뷰와 같은 비즈니스 도메인의 핵심 개념들을 리소스로 모델링하고, 이를 명확하게 표현하는 URL을 설계하는 것이 중요합니다.

• 명사 사용: URL에는 'getProducts'와 같은 동사 대신, 'products'와 같은 명사를 사용합니다. 특히 복수형 명사를 사용하는 것이 일반적입니다. [00:56]
• 계층 구조: 리소스는 컬렉션(전체 목록) 또는 개별 항목으로 구분될 수 있으며, 중첩된 관계도 명확하게 표현해야 합니다. [01:09]
  • /api/products: 모든 제품 목록을 가져옵니다. [01:14]
  • /api/products/{ID}: 특정 ID를 가진 제품 하나를 가져옵니다. [01:14]
  • /api/products/{ID}/reviews: 특정 제품에 달린 모든 리뷰 목록을 가져옵니다. [02:01]

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

실제 API에서는 방대한 양의 데이터를 한 번에 모두 반환하는 경우는 거의 없습니다. [02:31] 따라서 클라이언트가 원하는 데이터만 효율적으로 가져갈 수 있도록 쿼리 파라미터(Query Parameter)를 활용한 부가 기능을 제공해야 합니다.

• 필터링(Filtering): 특정 조건에 맞는 데이터만 걸러서 보여줍니다.
  • 예시: /products?category=electronics&in_stock=true (전자제품 카테고리 중 재고가 있는 상품만 조회) [02:46]
• 정렬(Sorting): 특정 기준에 따라 결과를 정렬합니다. 클라이언트가 직접 정렬하는 비효율을 막을 수 있습니다. [03:53]
  • 예시: ?sort=price_asc (가격을 오름차순으로 정렬) 또는 ?sort=reviews_desc (리뷰 개수를 내림차순으로 정렬) [03:18]
• 페이지네이션(Pagination): 대량의 데이터를 페이지 단위로 나누어 제공합니다. 서버 부하를 줄이고 성능을 향상시킵니다. [05:54]
  • 예시: /products?page=2&limit=10 (한 페이지에 10개씩, 2번째 페이지의 데이터를 조회) [04:26]
  • 이 외에도 offset 방식이나 커서(cursor) 기반 페이지네이션도 사용됩니다. [05:12]

3. 명확한 HTTP 메서드 사용

REST는 HTTP 프로토콜을 기반으로 하므로, 데이터 처리(CRUD)를 위해 각 목적에 맞는 HTTP 메서드를 명확하게 사용해야 합니다. [06:14]

• GET: 리소스 조회 (Read) [06:30]
• POST: 리소스 생성 (Create) - 멱등성(Idempotent)이 보장되지 않습니다. [07:08, 07:33]
• PUT: 리소스 전체 교체 (Update) [07:56]
• PATCH: 리소스 부분 수정 (Update) [08:05]
• DELETE: 리소스 삭제 (Delete) [08:50]

4. 정확한 상태 코드와 오류 처리

API는 요청 처리 결과를 명확하게 알려주기 위해 HTTP 상태 코드를 적절하게 사용해야 합니다. [09:25]

• 2xx (성공):
  • 200 OK: 요청 성공 (주로 GET) [09:41]
  • 201 Created: 리소스 생성 성공 (주로 POST) [10:18]
  • 204 No Content: 요청은 성공했지만 반환할 콘텐츠가 없음 (주로 DELETE) [09:44]
• 3xx (리디렉션): 리소스의 위치가 변경되었음을 알립니다. [10:31]
• 4xx (클라이언트 오류): 요청에 문제가 있음을 나타냅니다. [10:44]
  • 400 Bad Request: 잘못된 요청 (예: 파라미터 오류) [11:13]
  • 401 Unauthorized: 인증되지 않은 사용자의 요청 [10:59]
  • 404 Not Found: 요청한 리소스가 존재하지 않음 [11:06]
• 5xx (서버 오류): 서버 측에서 예상치 못한 오류가 발생했음을 나타냅니다. [11:41]
  • 500 Internal Server Error: 일반적인 서버 오류 [11:56]

REST API 모범 사례

• 복수형 명사 사용: 모든 리소스 URL에는 일관성 있게 복수형 명사를 사용하세요. (예: /product (X) -> /products (O)) [12:11]
• 적절한 HTTP 메서드 사용: CRUD 작업에 맞는 HTTP 메서드를 명확히 구분하여 사용하세요. [12:25]
• 필터링, 정렬, 페이지네이션 지원: 클라이언트의 편의성과 서버 효율성을 위해 반드시 지원하세요. [12:48]
• 버전 관리: API에 변경이 생길 때 기존 클라이언트에 영향을 주지 않도록 URL에 버전을 명시하세요. (예: /api/v1/products) [13:22] 이는 하위 호환성을 유지하는 데 매우 중요합니다. [13:43]

---

 

https://www.youtube.com/watch?v=DkSeXHS0kAQ