RESTful API와 HTTP: RESTful API 설계 원칙

REST(Representational State Transfer)는 웹 애플리케이션의 구조적 설계 방식 중 하나로, 클라이언트와 서버 간의 상호작용을 단순화하고 확장성을 극대화하는 원칙과 제약을 정의합니다. RESTful API는 이러한 원칙을 기반으로 설계된 API로, HTTP 프로토콜을 활용하여 자원(Resource)을 식별하고 조작하는 방식을 따릅니다.

RESTful API를 효과적으로 설계하려면 명확한 규칙을 준수하고, 확장성과 보안성을 고려한 구조를 설계해야 합니다. 이번 글에서는 REST의 기본 개념과 함께 RESTful API 설계 시 고려해야 할 원칙들을 자세히 살펴보겠습니다.

---

1. REST의 기본 개념

REST는 여러 원칙을 기반으로 하며, 웹 애플리케이션이 표준화된 방식으로 데이터를 교환할 수 있도록 합니다. 이를 위해 각 리소스를 고유하게 식별하고, HTTP 메서드를 사용하여 자원을 조작하는 방식을 따릅니다.

✅ 1) 자원(Resource) 기반 설계

REST에서는 모든 데이터와 기능을 "자원(Resource)" 으로 취급하며, 각 자원은 고유한 URI(Uniform Resource Identifier) 를 통해 접근할 수 있습니다.

✔ 예시 – 자원의 URI 구조:

• 사용자의 정보를 조회 → GET /users/{userId}
• 특정 게시글 조회 → GET /posts/{postId}
• 제품 목록 조회 → GET /products

이러한 구조를 유지하면 API의 가독성이 향상되며, 명확한 자원 식별 방식을 유지할 수 있습니다.

---

✅ 2) 상태 전이 (State Transition)와 상태 비저장성

클라이언트는 서버에서 제공하는 리소스를 요청하여 이를 통해 상태(State)를 변경할 수 있습니다. 예를 들어, 사용자가 특정 상품 정보를 요청하면 해당 상품의 상태가 클라이언트에게 전달됩니다.

또한 REST는 "무상태(Stateless)" 원칙을 준수해야 합니다.

• 각 요청은 독립적으로 처리되며, 서버는 클라이언트의 이전 요청 정보를 저장하지 않습니다.
• 클라이언트가 요청을 보낼 때 모든 필요한 정보를 포함하여 보내야 하며, 이는 서버의 부담을 줄이고 확장성을 향상시키는 데 기여합니다.

✔ 예시 – 상태 비저장 API 요청:

GET /users/123 HTTP/1.1  
Host: api.example.com  
Authorization: Bearer 

위 요청에서는 사용자의 로그인 상태를 유지하지 않고, 매번 Authorization 헤더를 통해 인증 정보를 함께 전달해야 합니다.

---

2. HTTP 메서드와 REST

RESTful API는 HTTP 메서드를 활용하여 CRUD(Create, Read, Update, Delete) 작업을 수행합니다.

HTTP 메서드	동작	설명	예제
GET	조회(Read)	특정 자원을 조회	GET /products/1
POST	생성(Create)	새로운 자원을 추가	POST /products
PUT	수정(Update)	기존 자원을 수정	PUT /products/1
DELETE	삭제(Delete)	특정 자원을 삭제	DELETE /products/1

✔ 예시 – 특정 제품 정보 수정 (PUT 요청):

PUT /products/10 HTTP/1.1  
Host: api.example.com  
Content-Type: application/json  

{
  "name": "무선 이어폰",
  "price": 89000
}

위 요청은 ID가 10인 제품의 정보를 수정하는 예제입니다.

---

3. RESTful API 설계 원칙

RESTful API를 설계할 때 반드시 고려해야 할 기본 원칙은 다음과 같습니다.

✅ 1) 무상태성 (Statelessness)

• 서버는 클라이언트의 상태를 저장하지 않으며, 각 요청은 독립적으로 처리되어야 합니다.
• 모든 요청은 필요한 정보를 포함하여 보내야 하며, 세션을 사용하지 않습니다.

✔ 예시 – JWT를 활용한 인증:

GET /users/123 HTTP/1.1  
Host: api.example.com  
Authorization: Bearer eyJhbGciOiJIUzI1NiIsIn...

✔ 장점:

• 서버 부담이 줄어들고 확장성이 향상됨
• 클라이언트-서버 간의 결합도가 낮아짐

---

✅ 2) 캐시 가능성 (Caching)

• RESTful API는 클라이언트가 데이터를 캐싱할 수 있도록 설계해야 합니다.
• Cache-Control 또는 Expires 헤더를 활용하여 캐싱 정책을 설정하면 성능이 향상됩니다.

✔ 예시 – 캐시 가능한 API 응답:

HTTP/1.1 200 OK  
Cache-Control: max-age=3600  
Content-Type: application/json  

{
  "id": 1,
  "name": "스마트폰",
  "price": 1000000
}

✔ 장점:

• 네트워크 트래픽 감소
• API 응답 속도 향상

---

✅ 3) 일관된 인터페이스 (Uniform Interface)

• RESTful API는 자원(Resource)와 행위(HTTP 메서드)를 일관된 방식으로 표현해야 합니다.
• 동일한 유형의 작업은 동일한 패턴을 따라야 합니다.

✔ 좋은 예:

GET /users      → 모든 사용자 조회  
GET /users/10   → 특정 사용자 조회  
POST /users     → 새로운 사용자 추가  

✔ 나쁜 예:

GET /getUsers  
POST /addNewUser  

✔ 장점:

• API 사용성이 높아지고, 예측 가능성이 증가함

---

✅ 4) 계층화 시스템 (Layered System)

• API는 여러 계층을 통해 구성될 수 있으며, 로드 밸런서, 프록시 서버, 보안 계층 등을 포함할 수 있어야 합니다.
• 클라이언트는 API의 내부 구조를 알 필요 없이 추상화된 형태로 상호작용할 수 있어야 합니다.

✔ 예시:

• API Gateway를 활용하여 다양한 백엔드 서비스와 연결

---

✅ 5) HATEOAS (Hypermedia as the Engine of Application State)

• 클라이언트가 API의 현재 상태를 기반으로 다음 동작을 예측할 수 있도록 링크를 포함해야 합니다.

✔ HATEOAS 적용 예시 – 제품 정보 응답:

{
  "id": 1,
  "name": "스마트폰",
  "price": 1000000,
  "links": [
    {"rel": "self", "href": "http://api.example.com/products/1"},
    {"rel": "update", "href": "http://api.example.com/products/1"},
    {"rel": "delete", "href": "http://api.example.com/products/1"}
  ]
}

✔ 장점:

• API 문서 없이도 클라이언트가 수행할 수 있는 작업을 예측 가능

---

결론

RESTful API는 현대 웹 및 모바일 애플리케이션에서 필수적인 기술로 자리 잡고 있습니다. 명확한 URI 설계, 상태 비저장성, 다양한 HTTP 메서드 활용, 그리고 HATEOAS 확장성을 통해 더 효율적이고 직관적인 API 설계가 가능합니다.

🚀 RESTful API를 활용하면, 개발자는 유지보수가 쉬운 API를 설계할 수 있으며, 사용자에게는 더 나은 서비스 경험을 제공할 수 있습니다.