REST API 란 무엇인가? (1/4)

본 문서는 REST API 시리즈 중 1편입니다. 이후 편에서는 다양한 플랫폼에서의 구현 방법을 다룰 예정입니다.

1. 개요

REST(Representational State Transfer)는 2000년 로이 필딩(Roy Fielding)의 박사 논문에서 제안된 소프트웨어 아키텍처 스타일로, 웹의 기존 기술과 HTTP 프로토콜을 활용하여 웹 서비스를 설계하는 방법론입니다. REST API는 이러한 REST 아키텍처 원칙을 따르는 애플리케이션 프로그래밍 인터페이스를 의미합니다.

---

2. REST 아키텍처의 기본 원칙

REST 아키텍처는 다음과 같은 6가지 기본 원칙을 기반으로 합니다:

원칙 설명

클라이언트-서버 구조	사용자 인터페이스와 데이터 저장 기능이 분리되어 있어야 합니다.
무상태성(Stateless)	서버는 클라이언트의 상태 정보를 저장하지 않으며, 각 요청은 독립적으로 처리되어야 합니다.
캐시 가능성(Cacheable)	응답은 캐시 가능 여부를 명시해야 하며, 가능한 경우 클라이언트에서 캐싱할 수 있어야 합니다.
계층화된 시스템(Layered System)	클라이언트는 직접 연결된 서버만 알면 되며, 중간 서버의 존재 여부는 알 필요가 없습니다.
인터페이스 일관성(Uniform Interface)	구성 요소 간 통일된 인터페이스로 전체 아키텍처가 단순화되고 상호작용의 가시성이 향상됩니다.
Code on Demand(선택 사항)	서버가 클라이언트에서 실행 가능한 코드를 전송하여 일시적으로 기능을 확장할 수 있습니다.

---

3. REST API의 주요 구성 요소

3.1 자원(Resources)

RESTful 시스템에서 모든 것은 자원으로 표현되며, 각 자원은 고유한 URI(Uniform Resource Identifier)를 통해 식별됩니다.

자원 URI 설계 원칙:

• 자원은 명사를 사용하여 표현합니다.
• 컬렉션은 복수형으로 표현합니다.
• 계층 관계는 슬래시(/)로 표현합니다.
• URI에는 소문자를 사용합니다.
• 단어 구분은 하이픈(-)을 사용합니다.

예시:

https://api.example.com/v1/customers
https://api.example.com/v1/customers/123
https://api.example.com/v1/customers/123/orders

3.2 HTTP 메서드

REST API는 HTTP 메서드를 사용하여 자원에 대한 행위를 정의합니다.

HTTP 메서드 의미 멱등성 안전성

GET	자원 조회	Y	Y
POST	자원 생성	N	N
PUT	자원 전체 수정	Y	N
PATCH	자원 부분 수정	N	N
DELETE	자원 삭제	Y	N
HEAD	헤더 정보만 조회	Y	Y
OPTIONS	지원 메서드 조회	Y	Y

• 멱등성(Idempotent): 동일한 요청을 여러 번 수행하더라도 동일한 결과가 나타남
• 안전성(Safe): 자원의 상태를 변경하지 않음

3.3 표현(Representations)

REST API에서는 클라이언트와 서버 간에 자원의 표현을 주고받습니다. 일반적으로 다음과 같은 형식이 사용됩니다:

형식 Content-Type 장점 단점

JSON	application/json	가독성 좋음, 언어 독립적, 경량	주석 미지원, 스키마 검증 별도 필요
XML	application/xml	스키마 검증 가능, 풍부한 메타데이터	비교적 무거움, 파싱 복잡
YAML	application/yaml	가독성 우수, 참조 지원	구현 복잡, 직렬화/역직렬화 느림

JSON 예시:

{
  "id": 123,
  "name": "John Doe",
  "email": "john@example.com",
  "created_at": "2023-04-01T10:30:00Z"
}

---

4. REST API 상태 코드

HTTP 상태 코드는 요청 처리 결과를 나타냅니다:

상태 코드 범위 의미 대표적인 상태 코드

2xx	성공	200 OK, 201 Created, 204 No Content
3xx	리다이렉션	301 Moved Permanently, 304 Not Modified
4xx	클라이언트 오류	400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found
5xx	서버 오류	500 Internal Server Error, 503 Service Unavailable

주요 상태 코드 상세 설명

상태 코드 설명 사용 예시

200 OK	요청이 성공적으로 처리됨	GET 요청에 대한 응답으로 자원 반환 시
201 Created	자원이 성공적으로 생성됨	POST 요청으로 새 자원 생성 시
204 No Content	요청은 성공했으나 반환할 내용 없음	DELETE 요청 성공 시
400 Bad Request	잘못된 형식의 요청	유효하지 않은 JSON 형식 전송 시
401 Unauthorized	인증 필요	로그인 필요한 API에 인증 없이 접근 시
403 Forbidden	접근 권한 없음	인증은 되었으나 권한이 부족할 때
404 Not Found	요청한 자원이 존재하지 않음	존재하지 않는 URI 접근 시
500 Internal Server Error	서버 내부 오류	서버 측 예외 발생 시

---

5. REST API 설계 모범 사례

5.1 버전 관리

API 버전을 관리하는 주요 방법:

방식 예시 장점 단점

URI 경로	/v1/customers	명시적, 구현 간단	URI 변경 필요
쿼리 파라미터	/customers?version=1	기존 URI 유지	선택적으로 보일 수 있음
헤더 사용	Accept: application/vnd.company.v1+json	URI 깔끔하게 유지	테스트 복잡

5.2 페이지네이션

대량의 데이터를 효율적으로 처리하기 위한 페이지네이션 구현:

GET /users?page=2&size=10

응답 예시:

{
  "data": [...],
  "pagination": {
    "total_items": 2500,
    "total_pages": 250,
    "current_page": 2,
    "items_per_page": 10,
    "next": "/users?page=3&size=10",
    "previous": "/users?page=1&size=10"
  }
}

5.3 필터링, 정렬 및 검색

기능 구현 방식 예시

필터링	쿼리 파라미터	/products?category=electronics&price_min=100&price_max=500
정렬	sort 파라미터	/products?sort=price:asc,name:desc
필드 선택	fields 파라미터	/users?fields=id,name,email
검색	q 파라미터	/articles?q=restful+api

5.4 에러 처리

일관된 오류 응답 형식 예시:

{
  "error": {
    "code": "INVALID_PARAMETER",
    "message": "The parameter 'email' is not a valid email address",
    "details": {
      "field": "email",
      "value": "not-an-email",
      "rule": "email"
    },
    "request_id": "request-123"
  }
}

---

6. REST API 보안 고려사항

보안 기법 설명 구현 방식

HTTPS	전송 계층 암호화	모든 API 엔드포인트에 SSL/TLS 인증서 적용
인증 토큰	사용자 인증	JWT, OAuth 2.0 토큰을 Authorization 헤더에 포함
요청 제한	서비스 남용 방지	Rate limiting 구현, 헤더로 제한 상태 전달
CORS	교차 출처 요청 제어	Access-Control-Allow-Origin 헤더 설정
입력 검증	악의적 입력 방지	모든 입력 파라미터 검증 및 Sanitization

---

7. API 문서화

효과적인 API 문서에 포함되어야 할 요소:

1. 엔드포인트 설명 및 URI
2. 지원하는 HTTP 메서드
3. 요청 파라미터 및 본문 형식
4. 응답 형식 및 예시
5. 인증 방법
6. 오류 코드 및 처리 방법
7. 사용 제한 사항

문서화 도구:

도구 특징 적합한 상황

Swagger/OpenAPI	상호작용 가능한 문서, 코드 생성	대규모 API, 자동화 원할 때
API Blueprint	간결한 마크다운 기반 문서	설계 중심, 간단한 API
Postman	API 테스트와 문서화 통합	테스트 중심 접근
GitBook	버전 관리와 통합된 문서	오픈소스 프로젝트

---

8. REST API와 다른 API 스타일 비교

API 스타일 특징 장점 단점 적합한 상황

REST API	HTTP 메서드, 자원 중심	단순함, 확장성, 캐싱	오버페칭/언더페칭	일반적인 웹 서비스
GraphQL	클라이언트 중심 쿼리	필요한 데이터만 요청	구현 복잡, 캐싱 어려움	다양한 클라이언트 요구사항
gRPC	프로토콜 버퍼, HTTP/2	고성능, 강력한 타입	브라우저 지원 제한	마이크로서비스 간 통신
SOAP	XML 기반, 프로토콜 독립적	강력한 표준, 보안	무거움, 복잡함	엔터프라이즈 환경

---

9. RESTful API 성숙도 모델 (Richardson Maturity Model)

레벨 설명 특징

레벨 0	HTTP 터널링	단일 URI, 단일 HTTP 메서드(주로 POST)
레벨 1	자원	여러 URI(자원)를 사용하지만 HTTP 메서드는 제한적
레벨 2	HTTP 동사	적절한 HTTP 메서드 사용, 상태 코드 활용
레벨 3	HATEOAS	응답에 다음 가능한 액션에 대한 링크 포함

---

10. 결론

REST API는 웹의 기존 인프라를 활용하는 단순하고 확장성 있는 아키텍처 스타일로, 다양한 클라이언트 애플리케이션에서 접근할 수 있는 서비스를 구축하는 데 매우 효과적입니다. 이 문서에서 설명한 원칙과 모범 사례를 따라 설계된 REST API는 견고하고, 확장 가능하며, 개발자 친화적인 인터페이스를 제공할 수 있습니다.

---

11. 후속 시리즈 안내

본 문서는 REST API에 대한 기본 개념과 설계 원칙을 다루는 시리즈의 첫 번째 편입니다. 앞으로 계속될 시리즈에서는 다양한 환경에서의 REST API 구현 방법을 상세히 다룰 예정입니다:

 

시리즈 제목 주요 내용

1편	REST API란 무엇인가?	REST API에 대해 알아보기
2편	Spring Boot에서의 REST API 작성 예시	Spring Boot 프레임워크를 활용한 REST API 구현 방법
3편	Nest.JS에서의 REST API 작성 예시	Node.js 기반 Nest.JS 프레임워크에서의 REST API 개발
4편	그 외 플랫폼에서의 REST API 작성 예시	Django, Flask, Express.js 등 다양한 프레임워크에서의 구현

 

각 편에서는 해당 프레임워크의 특성을 살린 REST API 설계 및 구현 방법, 보안 처리, 테스트 방법 등을 실제 코드 예제와 함께 제공할 예정입니다.

---

부록: REST API 구현 예시

사용자 관리 API 예시

엔드포인트 메서드 설명 요청 본문 응답 형식 상태 코드

/users	GET	사용자 목록 조회	-	사용자 배열	200
/users	POST	신규 사용자 생성	사용자 정보	생성된 사용자	201
/users/{id}	GET	특정 사용자 조회	-	사용자 객체	200
/users/{id}	PUT	사용자 정보 전체 수정	전체 사용자 정보	수정된 사용자	200
/users/{id}	PATCH	사용자 정보 일부 수정	수정할 필드만	수정된 사용자	200
/users/{id}	DELETE	사용자 삭제	-	-	204
/users/{id}/posts	GET	사용자의 게시물 조회	-	게시물 배열	200