REST API 설계 베스트 프랙티스: 좋은 API를 만드는 10가지 원칙

API 설계가 중요한 이유

API(Application Programming Interface)는 소프트웨어 간의 계약입니다. 잘 설계된 API는 개발 생산성을 높이고, 잘못 설계된 API는 끊임없는 혼란과 버그를 야기합니다.

REST API 설계 원칙

1. 리소스 중심 설계

URL은 동사가 아닌 명사로, 리소스를 표현합니다.

Bad

• GET /getUsers
• POST /createUser
• DELETE /deleteUser/1

Good

• GET /users
• POST /users
• DELETE /users/1

2. HTTP 메서드 올바르게 사용

멱등성(Idempotency): 같은 요청을 여러 번 보내도 결과가 같음

3. 적절한 HTTP 상태 코드

성공 (2xx)

• 200: 성공
• 201: 생성됨
• 204: 내용 없음 (삭제 성공)

클라이언트 오류 (4xx)

• 400: 잘못된 요청
• 401: 인증 필요
• 403: 권한 없음
• 404: 찾을 수 없음
• 409: 충돌

서버 오류 (5xx)

• 500: 서버 내부 오류
• 503: 서비스 일시 중단

요청/응답 설계

요청 (Request)

Query Parameters: 필터링, 정렬, 페이지네이션

• GET /users?status=active&sort=created_at&page=1

Path Parameters: 특정 리소스 식별

• GET /users/123
• GET /users/123/orders/456

Request Body: 생성/수정 데이터 (JSON)

응답 (Response)

일관된 응답 구조 성공과 실패 모두 예측 가능한 구조를 사용합니다. data, error, meta 필드를 일관되게 사용합니다.

페이지네이션 대량 데이터는 반드시 페이지네이션합니다. 커서 기반이 오프셋 기반보다 대규모에서 효율적입니다.

버전 관리

API는 변경될 수 있습니다. 기존 사용자에게 영향을 주지 않으면서 새 기능을 추가해야 합니다.

버전 관리 방법

URL 경로 (권장)

• /v1/users
• /v2/users

헤더

• Accept: application/vnd.api+json; version=1

쿼리 파라미터

• /users?version=1

보안

인증 (Authentication)

JWT (JSON Web Token)

• 상태 없는(stateless) 인증
• Authorization: Bearer <token>

API Key

• 간단한 시나리오에 적합
• 헤더: X-API-Key: <key>

인가 (Authorization)

• RBAC (Role-Based Access Control)
• 리소스별 권한 체크
• 최소 권한 원칙

보안 베스트 프랙티스

• HTTPS 필수
• 입력 검증
• Rate Limiting
• SQL Injection 방지
• CORS 설정

문서화

좋은 API는 좋은 문서와 함께합니다.

OpenAPI (Swagger)

API 스펙을 YAML/JSON으로 정의합니다.

• 자동 문서 생성
• 클라이언트 SDK 자동 생성
• 테스트 UI 제공

문서에 포함할 내용

• 엔드포인트 목록
• 요청/응답 예시
• 인증 방법
• 에러 코드 설명
• Rate Limit 정보

성능 최적화

1. 캐싱

• ETags
• Cache-Control 헤더
• Redis 캐시

2. 압축

• gzip 압축
• 응답 크기 최소화

3. 필드 선택

• ?fields=id,name,email
• 필요한 데이터만 요청

4. 배치 처리

• 여러 요청을 하나로 묶기
• GraphQL 고려

테스트

자동화 테스트

• 단위 테스트
• 통합 테스트
• 계약 테스트

도구

• Postman
• Insomnia
• curl

마무리

잘 설계된 API는 개발 경험을 크게 향상시킵니다. SpacePlanning은 RESTful API 설계 및 개발 서비스를 제공합니다.