1. REST API와 RESTful API 비교

1.1 REST API란?

REST API는 REST(Representational State Transfer) 아키텍처 스타일을 따르는 API(Application Programming Interface)를 의미합니다. REST는 웹에서 리소스(데이터)를 효율적으로 전송하는 방식으로, 주로 HTTP를 기반으로 합니다. REST API는 클라이언트와 서버 간의 통신을 효율적으로 설계하고 리소스(데이터)를 HTTP 메서드를 통해 전달하는 방식입니다.

REST API는 REST(Representational State Transfer) 아키텍처 스타일을 따르는 API(Application Programming Interface)를 의미합니다.

REST는 웹에서 리소스를 효율적으로 전송하는 방식으로, HTTP 프로토콜을 기반으로 동작합니다.

REST API의 주요 개념은 다음과 같습니다.

리소스(Resource): API에서 다루는 데이터(예: 사용자, 게시글, 상품 등)
HTTP 메서드(Verb): GET, POST, PUT, DELETE 등을 사용하여 리소스를 조작
URI(Uniform Resource Identifier): 리소스를 식별하는 고유한 주소

📌 REST API 예제 (특정 사용자의 정보를 조회하는 REST API 요청)

GET /api/v1/users/123 HTTP/1.1
Host: www.example.com

/api/v1/users/123: 123번 사용자의 정보를 조회하는 요청
GET: 데이터를 조회하는 HTTP 메서드
Host: www.example.com: 서버 주소

1.2 RESTful API란?

RESTful API는 REST의 원칙을 철저히 준수하는 API를 의미합니다.

즉, 단순히 REST 방식을 사용했다고 해서 RESTful API가 되는 것이 아니라, 아래 REST의 6가지 원칙을 정확히 따라야 합니다.

클라이언트-서버 구조
무상태성(Statelessness)
캐시 가능(Cacheability)
계층화된 시스템(Layered System)
코드 온디맨드(Code on Demand) [선택적]
리소스 기반 URI(Uniform Interface)

📌 RESTful API 예제 (RESTful API에서 사용자의 정보를 가져오는 요청)

GET /api/v1/users/123 HTTP/1.1
Host: www.example.com
Authorization: Bearer <token>

Authorization: Bearer <token>: 무상태성을 유지하기 위해 토큰 기반 인증을 사용
/api/v1/users/123: 명사형 URI 사용
리소스를 명확하게 식별하고, HTTP 메서드에 맞게 설계됨

2. REST API와 RESTful API의 차이점

구분	REST API	RESTful API
정의	REST 방식을 기반으로 API를 설계한 모든 API	REST 원칙을 엄격하게 준수한 API
무상태성	상태 정보를 유지할 수도 있음	클라이언트의 상태를 저장하지 않음
리소스 URI 설계	동사 기반 URI 사용 가능 (예: `/getUserInfo`)	명사형 리소스 기반 URI 사용 (예: `/users/123`)
HTTP 메서드 사용	모든 요청을 `POST`로 처리하는 경우도 있음	`GET`, `POST`, `PUT`, `DELETE` 등 올바른 메서드 사용
캐시 가능성	캐싱을 고려하지 않을 수도 있음	응답에 `Cache-Control`을 설정하여 최적화
확장성	RESTful 원칙을 따르지 않으면 유지보수 어려움	REST 원칙을 따르면 유지보수 용이

3. REST의 6가지 기본 원칙을 통해 RESTful API와 REST API 비교하기

3.1 클라이언트-서버 구조 (Client-Server Architecture)

REST API: 클라이언트-서버 구조를 따를 수 있지만, 클라이언트와 서버 간의 역할이 모호할 수 있고, 서버에서 상태 정보를 유지하는 경우가 있습니다.
RESTful API: 클라이언트와 서버가 명확히 분리되어 있으며, 서버는 클라이언트의 상태를 저장하지 않습니다. 클라이언트는 요청만 보내고, 서버는 필요한 리소스만 제공하여 서로 독립적으로 발전할 수 있습니다.

📌 예제

GET /api/v1/products HTTP/1.1
Host: www.example.com

클라이언트는 요청만 보내고, 서버는 필요한 데이터만 제공

3.2 무상태성 (Statelessness)

REST API: 일부 API는 무상태성을 지키지 않고 서버에 세션 데이터를 유지할 수 있습니다.
RESTful API: 모든 요청이 독립적이어야 하며, 서버는 클라이언트의 상태 정보를 저장하지 않습니다. 각 요청은 필요한 정보를 모두 포함하여 보내야 합니다.(예: 인증 정보)

📌 예제

GET /api/v1/products HTTP/1.1
Host: www.example.com
Authorization: Bearer <token>

매 요청마다 인증 정보(Bearer <token>)를 포함하여 서버가 상태를 저장하지 않음

3.3 리소스 기반 URI (Resource-Based URIs)

REST API: URI 설계가 리소스 중심이 아닐 수 있으며, 종종 동사로 설계된 경우가 많습니다. 예를 들어, GET /getUserInfo와 같은 같은 동사 기반 URI를 사용할 수도 있습니다.
RESTful API: /users/123 처럼 명사형 URI 사용하며, *URI는 *리소스에 접근하는 방식을 명확히 나타냅니다.

📌 예제

GET /api/v1/users/123  # 특정 사용자 리소스 조회
POST /api/v1/users     # 새로운 사용자 추가

RESTful API에서는 URI는 리소스 자체를 의미해야 하며 동사는 사용하지 않음

3.4 HTTP 메서드 활용 (Use of HTTP Methods)

REST API: 모든 HTTP 메서드를 RESTful하지 않게 사용하는 경우가 있습니다. 예를 들어, 데이터 조회나 수정에 관계없이 모든 요청이 POST 메서드를 사용하는 API가 있을 수 있습니다.
RESTful API: HTTP 메서드를 목적에 맞게 사용합니다. 데이터 조회는 GET, 리소스 추가는 POST, 수정은 PUT, 삭제는 DELETE와 같이 사용합니다.

📌 예제

GET /api/v1/users     # 사용자 목록 조회
POST /api/v1/users    # 사용자 생성
PUT /api/v1/users/1   # 사용자 정보 수정
DELETE /api/v1/users/1 # 사용자 삭제

각 메서드는 그에 맞는 작업을 처리하도록 구분되어 있습니다.

3.5 표현 계층 (Layered System)

REST API: 클라이언트와 서버 사이에 중간 계층을 사용할 수 있지만, RESTful하지 않게 중간 계층이 클라이언트와 서버의 동작을 방해할 수 있습니다.
RESTful API: 여러 계층이 존재할 수 있으며, 각 계층은 독립적으로 동작합니다. 클라이언트는 중간에 프록시 서버나 로드 밸런서 등의 계층이 있더라도 이를 인지할 필요가 없습니다.

3.6 캐시 가능성 (Cacheability)

REST API: 서버가 캐싱 가능성을 명시하지 않거나 잘못된 캐시 처리 정책을 사용할 수 있습니다.
RESTful API: 서버가 응답에 캐싱 가능 여부를 명시해주면, 클라이언트는 데이터를 캐시하고 성능을 최적화할 수 있습니다.

📌 예제

GET /api/v1/products HTTP/1.1
Cache-Control: max-age=3600  # 1시간 동안 캐시 가능

서버는 응답에 캐싱 정보를 포함시켜 클라이언트가 데이터를 캐시할 수 있게 합니다.

4. RESTful API를 구현할 때 고려해야 할 사항

RESTful API를 설계할 때는 단순히 REST 원칙을 따르는 것뿐만 아니라, 보안, 성능, 버전 관리, 응답 표준화 등 다양한 요소를 고려해야 합니다. RESTful API를 제대로 설계하면 확장성과 유지보수성이 뛰어난 API를 만들 수 있습니다.

4.1 Restful API 보안 (Security)

RESTful API는 HTTP 기반의 공개된 API이므로, 보안이 매우 중요합니다. API 설계 시 인증(Authentication), 권한 관리(Authorization), 데이터 암호화 등을 고려해야 합니다.

RESTful API 보안 고려사항으로는 다음과 같습니다.

인증(Authentication) → OAuth 2.0, JWT(JSON Web Token) 등을 활용
권한 관리(Authorization) → API 사용자의 역할(Role)별 권한 부여
HTTPS 사용 → HTTP 대신 HTTPS로 통신하여 보안 강화
API Rate Limiting → 요청 횟수를 제한하여 DoS 공격 방지
CORS (Cross-Origin Resource Sharing) 설정 → API 접근 제어

📌 JWT를 이용한 인증 예제

GET /api/v1/users/me HTTP/1.1
Host: www.example.com
Authorization: Bearer <JWT-Access-Token>

클라이언트는 API 요청 시 JWT 토큰을 Authorization 헤더에 포함
서버는 해당 토큰을 검증하여 요청을 처리

4.2 RESTful API 성능 최적화 (Performance Optimization)

API는 클라이언트 요청을 빠르게 처리해야 하며, 불필요한 데이터 전송을 최소화해야 합니다.

성능 최적화를 위한 고려 사항으로는 다음과 같습니다.

Pagination (페이징 처리)
- 대량의 데이터를 조회할 때, 한 번에 모든 데이터를 보내지 않고 페이지 단위로 나눠 전송
- limit, offset 또는 cursor-based pagination 방식 사용

📌 페이징 API 예제

GET /api/v1/products?limit=10&offset=20

필드 선택 (Selective Fields / Sparse Fieldsets)
- 클라이언트가 필요한 데이터만 요청하도록 API에서 필드 선택 기능 제공

📌 특정 필드만 응답하는 API 예제

GET /api/v1/users/123?fields=id,name,email

데이터 압축 (Gzip, Brotli) 적용
- 서버가 Gzip이나 Brotli 압축을 지원하여 네트워크 트래픽 감소

📌 Gzip 압축 예제

GET /api/v1/data HTTP/1.1
Accept-Encoding: gzip

캐싱(Cache Control) 활용
- Cache-Control 헤더를 사용하여 불필요한 요청을 줄이고, 성능을 최적화

📌 캐싱 적용 예제

Cache-Control: public, max-age=3600

4.3 RESTful API 버전 관리 (API Versioning)

API는 시간이 지나면서 변경될 수 있으므로, 기존 클라이언트에 영향을 주지 않기 위해 버전 관리가 필요합니다.

API 버전 관리 방법으로는 다음과 같습니다.

URI 버전 관리 (URL Versioning)
- 가장 일반적인 방법으로, API URL에 버전 번호 포함

GET /api/v1/users/123

HTTP 헤더 기반 버전 관리
- Accept 헤더에 버전 정보를 추가하여 요청

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

쿼리 파라미터 기반 버전 관리
- URL 쿼리 파라미터로 버전 지정

GET /api/users/123?version=1

추천: URI 기반 버전 관리 방식이 가장 널리 사용되며, 명확한 버전 구분이 가능합니다.

4.4 RESTful API 응답 표준화 (Standardized API Responses)

API의 응답(Response)은 일관된 형식을 유지해야 클라이언트가 쉽게 데이터를 처리할 수 있습니다.

📌 RESTful API 응답 형식 예시 (JSON Format) → 성공 응답 (200 OK)

{
    "status": "success",
    "data": {
        "id": 123,
        "name": "John Doe",
        "email": "john@example.com"
    }
}

📌 RESTful API 응답 형식 예시 (JSON Format) → 에러 응답 (400 Bad Request)

{
    "status": "error",
    "message": "Invalid request parameters",
    "errors": {
        "email": "Email is required",
        "password": "Password must be at least 6 characters"
    }
}

참고) HTTP 상태 코드 (HTTP Status Codes) 정리

상태 코드	설명
200 OK	요청 성공
201 Created	리소스 생성 성공
400 Bad Request	클라이언트 요청 오류
401 Unauthorized	인증 실패 (로그인 필요)
403 Forbidden	접근 권한 없음
404 Not Found	요청한 리소스 없음
500 Internal Server Error	서버 내부 오류

4.5 Restful API 문서화 (API Documentation)

API를 여러 개발자가 함께 사용하려면 API 문서화가 필수적입니다.

API 문서화 방법은 다음과 같습니다.

Swagger (OpenAPI) 활용
- Swagger UI를 사용하여 API 스펙을 시각적으로 문서화 가능
Postman을 활용한 API 문서화
- Postman으로 API 테스트 및 문서 생성 가능

추천: Swagger(OpenAPI)를 활용하면 API 문서를 자동 생성할 수 있어 유지보수에 용이합니다.

5. 결론

REST API와 RESTful API는 비슷해 보이지만, RESTful API는 REST의 원칙을 엄격하게 준수하는 API를 의미합니다. RESTful API를 올바르게 설계하면 확장성, 유지보수성, 보안성이 뛰어난 API를 구축할 수 있습니다.

REST API vs RESTful API 핵심 정리
- REST API는 REST 아키텍처를 기반으로 설계된 모든 API를 의미하지만, 반드시 RESTful한 원칙을 따르는 것은 아닙니다.
- RESTful API는 REST의 6가지 원칙(클라이언트-서버, 무상태성, 캐싱, 계층 구조 등)을 철저히 준수하는 API입니다.
- RESTful API를 구현하려면 올바른 HTTP 메서드 사용, 명사 기반 URI 설계, 상태 저장 금지(Stateless) 등의 원칙을 따라야 합니다.
RESTful API를 설계할 때 고려해야 할 사항
- 보안 강화 → JWT 인증, HTTPS 사용, API Rate Limiting 적용
- 성능 최적화 → 페이징, 데이터 압축(Gzip), 캐싱(Cache-Control) 활용
- 버전 관리 → URI 버전(v1, v2), HTTP 헤더 기반 버전 관리 적용
- 응답 표준화 → API 응답(JSON 형식) 일관성 유지, HTTP 상태 코드 명확히 정의
- 문서화 → Swagger(OpenAPI) 등을 사용하여 API 명세를 체계적으로 관리

RESTful API를 제대로 설계하면 확장성과 유지보수성이 뛰어난 API를 구축할 수 있으며, 개발 및 운영 효율성을 극대화할 수 있습니다.

[Web] RESTful API란? REST API와의 차이점과 구현 원칙 정리

1. REST API와 RESTful API 비교

1.1 REST API란?

1.2 RESTful API란?

2. REST API와 RESTful API의 차이점

3. REST의 6가지 기본 원칙을 통해 RESTful API와 REST API 비교하기

3.1 클라이언트-서버 구조 (Client-Server Architecture)

3.2 무상태성 (Statelessness)

3.3 리소스 기반 URI (Resource-Based URIs)

3.4 HTTP 메서드 활용 (Use of HTTP Methods)

3.5 표현 계층 (Layered System)

3.6 캐시 가능성 (Cacheability)

4. RESTful API를 구현할 때 고려해야 할 사항

4.1 Restful API 보안 (Security)

4.2 RESTful API 성능 최적화 (Performance Optimization)

4.3 RESTful API 버전 관리 (API Versioning)

4.4 RESTful API 응답 표준화 (Standardized API Responses)

참고) HTTP 상태 코드 (HTTP Status Codes) 정리

4.5 Restful API 문서화 (API Documentation)

5. 결론

티스토리툴바