REST API 완벽 가이드: MSA 환경에서의 효율적인 서비스 간 통신 설계

마이크로서비스 아키텍처(MSA)에서 서비스 간 통신을 위해 REST API를 채택하는 것은 매우 일반적입니다. REST API는 네트워크를 통해 리소스를 효율적으로 관리하고, 클라이언트와 서버 간의 상호작용을 간단하게 만들어줍니다.
이번 포스트에서는 REST API의 구성 요소, 설계 원칙, HTTP 메소드, 응답 코드, 특성 및 설계 원칙에 대해 더 깊이 있게 살펴보겠습니다.

---

REST API의 구성 요소

앞으로 이해도를 높이기 위해 "호텔관리 시스템 API"를 기준으로 설명하겠습니다.

리소스 (Resource)

• 정의: 리소스는 REST API에서 표현되는 대상이며, HTTP URL로 식별됩니다. 리소스는 데이터베이스의 엔티티와 일치하거나, 비즈니스 도메인을 모델링합니다
• 예시:
  • 모든 호텔 정보는 /hotels로 표현됩니다
  • 특정 호텔인 힐튼 호텔은 /hotels/hilton으로 표현되며, 식별자는 일반적으로 숫자를 사용해 /hotels/2342와 같이 표현합니다

행위 (Verb)

• 정의: 리소스에 대한 행위는 HTTP 메소드로 표현됩니다. 각 메소드는 리소스에 대해 수행할 수 있는 CRUD(Create, Read, Update, Delete) 작업을 나타냅니다
• 예시:
  • GET: 리소스 정보를 조회 (예: /hotels)
  • POST: 클라이언트가 HTTP 메시지 바디에 전송한 데이터를 리소스에 생성 (예: /hotels)
  • PUT: 리소스 객체를 전체 수정 (예: /hotels/2342)
  • DELETE: 리소스를 삭제 (예: /hotels/2342)

표현 (Representation)

• 정의: 리소스에 대한 행위의 내용은 HTTP 메시지의 내용으로 표현됩니다. 일반적으로 JSON 포맷을 사용하지만, XML, HTML 등 다른 포맷도 사용할 수 있습니다
• 예시: 호텔 정보를 JSON 포맷으로 표현할 수 있습니다

{
    "id": 2342,
    "name": "Hilton Hotel",
    "location": "New York",
    "rooms": [
        {
            "number": 101,
            "type": "Single",
            "price": 100
        }
    ]
}

---

REST API 설계 원칙

리소스 이름

• 명사 사용: 리소스 이름은 동사보다 명사를 사용해야 합니다. 이는 REST의 자원 지향적인 특성을 강조합니다
• 복수 형태: 리소스는 복수 형태로 표현하여, 여러 개의 리소스를 다룰 수 있음을 나타냅니다. 예를 들어, 호텔 목록은 /hotels로 표현합니다

계층적 구조

리소스는 계층적 구조를 가질 수 있습니다. 예를 들어, 특정 호텔의 방 정보를 표현할 때는 /hotels/hilton/rooms/101과 같이 표현합니다. 이렇게 하면 리소스 간의 관계를 명확히 할 수 있습니다.

HTTP 메소드

기본적으로 GET, POST, PUT, DELETE 메소드를 사용하며, 필요 시 PATCH 메소드를 사용할 수 있습니다. 각 메소드는 특정 작업을 수행하는 데 적합하게 설계되어 있습니다.

RESTful한 URI 설계 예시

# 좋은 URI 설계 예시
GET /users              # 사용자 목록 조회
GET /users/{id}         # 특정 사용자 조회
POST /users             # 새로운 사용자 생성
PUT /users/{id}         # 사용자 정보 전체 수정
PATCH /users/{id}       # 사용자 정보 일부 수정
DELETE /users/{id}      # 사용자 삭제

# 나쁜 URI 설계 예시
GET /get-users          # 동사 사용
GET /users/get/{id}     # 중복된 동사
POST /create-user       # 불필요한 동사
DELETE /users/delete/{id} # 중복된 의미

---

HTTP 메소드 별 REST API 예제

HTTP 메소드	설명	예시	멱등성	안전성
GET	리소스 정보를 조회	/hotels	O	O
POST	클라이언트가 HTTP 메시지 바디에 전송한 데이터를 리소스에 생성	/hotels	X	X
PUT	정의된 리소스 객체를 전체 수정	/hotels/2342	O	X
DELETE	정의된 리소스를 삭제	/hotels/2342	O	X
PATCH	정의된 리소스의 일부 데이터를 수정	/hotels/2342	X	X

REST API 버전 관리

• URI에 따라 구분: URI에 버전 정보를 포함할 수 있습니다. 예를 들어, /v1/hotels와 같이 표현합니다
• 헤더 정보에 따라 구분: HTTP 헤더에 REST API 버전을 포함시켜 요청하고, 응답 메시지에도 버전 정보를 포함하여 반환할 수 있습니다. 예를 들어, Accept: application/vnd.myapi.v1+json과 같이 요청할 수 있습니다

---

응답 코드

HTTP 응답 코드는 클라이언트의 요청 처리 결과를 나타냅니다. 주요 응답 코드는 다음과 같습니다:

2XX (성공)

• 200 OK: 클라이언트 요청을 성공적으로 처리했습니다
• 201 Created: 클라이언트 요청으로 데이터를 성공적으로 생성했습니다. 보통 200 OK와 통일해서 사용합니다
• 204 No Content: 요청은 성공했으나 응답할 콘텐츠가 없음

4XX (클라이언트 오류)

• 400 Bad Request: 클라이언트 요청이 유효하지 않을 때 발생합니다
• 401 Unauthorized: 인증받지 않은 클라이언트가 요청할 때 발생합니다 (예: 로그인 실패)
• 403 Forbidden: 인가되지 않은 클라이언트가 요청할 때 발생합니다 (예: 권한 실패)
• 404 Not Found: 찾을 수 없는 페이지, 주소를 잘못 입력했을 때 사용함
• 409 Conflict: 서버가 요청을 처리하는 과정에서 충돌이 발생한 경우

5XX (서버 오류)

• 500 Internal Server Error: 서버에서 요청을 정상적으로 처리하지 못했을 때 발생합니다
• 502 Bad Gateway: 서버로 가는 요청이 중간에서 유실된 경우
• 503 Service Unavailable: 서버가 터졌거나 유지 보수 중

---

REST API 특성과 설계 원칙

무상태성 (Statelessness)

• 정의: REST API는 클라이언트와 서버 간의 모든 요청이 독립적이며, 서버는 클라이언트의 상태를 저장하지 않습니다. 각 요청은 필요한 모든 정보를 포함해야 하며, 이전 요청의 상태에 의존하지 않습니다
• 장점:
  • 확장성: 서버는 클라이언트의 상태를 관리하지 않으므로, 여러 서버에 요청을 분산하는 것이 용이합니다
  • 가용성: 서버의 가용성을 높여주며, 클라이언트와 서버 간의 연결이 끊어져도 다른 요청을 처리하는 데 영향을 미치지 않습니다

일관성 (Consistency)

• 정의: REST API는 동일한 형태의 메시지 및 HTTP 상태 코드를 정의해야 하며, 클라이언트가 예측할 수 있는 일관된 응답을 제공합니다
• 장점:
  • 사용자 경험 향상: 사용자나 개발자가 API를 사용할 때, 일관된 응답 형식과 상태 코드를 통해 쉽게 이해하고 사용할 수 있습니다
  • 디버깅 용이: 일관된 메시지와 상태 코드는 오류를 추적하고 수정하는 데 도움이 됩니다

멱등성 (Idempotence)

• 정의: 멱등성은 동일한 API를 여러 번 호출해도 결과가 동일해야 함을 의미합니다. 즉, API를 여러 번 호출하더라도 서버의 상태가 변하지 않아야 합니다

HTTP 메소드와 멱등성:

• GET: 멱등성. 요청을 반복해도 결과는 동일하며, 서버의 상태를 변경하지 않습니다
• PUT: 멱등성. 동일한 데이터로 여러 번 업데이트해도 결과는 같습니다
• DELETE: 멱등성. 동일한 리소스를 여러 번 삭제해도 결과는 같습니다
• POST: 일반적으로 멱등성이 없습니다. 같은 요청을 여러 번 보낼 경우, 여러 개의 리소스가 생성될 수 있습니다

캐시 가능성 (Cacheability)

• 정의: REST API는 응답이 캐시 가능하다는 것을 명시할 수 있습니다. 클라이언트는 이전 요청의 결과를 캐시하여 다음 요청 시 재사용할 수 있습니다
• 장점:
  • 성능 향상: 캐시된 데이터를 사용하면 서버에 대한 요청 수를 줄이고, 응답 시간을 단축할 수 있습니다
  • 대역폭 절약: 반복적인 요청에 대한 응답을 캐시하면 네트워크 사용량을 줄일 수 있습니다
• HTTP 헤더: Cache-Control, Expires, ETag와 같은 HTTP 헤더를 사용하여 캐시 정책을 정의합니다

계층화 (Layered System)

• 정의: REST API는 클라이언트와 서버 간에 여러 계층을 두어 아키텍처를 설계할 수 있습니다. 각 계층은 자신의 기능을 수행하며, 클라이언트는 최종 서버와 직접 연결되지 않고 중간 계층을 통해 통신할 수 있습니다
• 장점:
  • 보안: 중간 계층을 통해 보안 정책을 적용할 수 있습니다
  • 유지보수: 각 계층의 기능을 독립적으로 개발하고 변경할 수 있어, 시스템 유지보수가 용이합니다

Spring Boot에서의 REST API 구현 예시

@RestController
@RequestMapping("/api/v1/hotels")
@Validated
public class HotelController {

    @Autowired
    private HotelService hotelService;

    @GetMapping
    public ResponseEntity> getAllHotels(
            @RequestParam(defaultValue = "0") int page,
            @RequestParam(defaultValue = "10") int size) {

        List hotels = hotelService.findAll(page, size);
        return ResponseEntity.ok()
            .cacheControl(CacheControl.maxAge(Duration.ofMinutes(5)))
            .body(hotels);
    }

    @GetMapping("/{id}")
    public ResponseEntity getHotel(@PathVariable Long id) {
        Hotel hotel = hotelService.findById(id);
        return ResponseEntity.ok()
            .eTag(String.valueOf(hotel.getVersion()))
            .body(hotel);
    }

    @PostMapping
    public ResponseEntity createHotel(@Valid @RequestBody Hotel hotel) {
        Hotel savedHotel = hotelService.save(hotel);
        return ResponseEntity.status(HttpStatus.CREATED)
            .location(URI.create("/api/v1/hotels/" + savedHotel.getId()))
            .body(savedHotel);
    }

    @PutMapping("/{id}")
    public ResponseEntity updateHotel(
            @PathVariable Long id, 
            @Valid @RequestBody Hotel hotel) {
        Hotel updatedHotel = hotelService.update(id, hotel);
        return ResponseEntity.ok(updatedHotel);
    }

    @DeleteMapping("/{id}")
    public ResponseEntity deleteHotel(@PathVariable Long id) {
        hotelService.delete(id);
        return ResponseEntity.noContent().build();
    }
}

---

결론

REST API 설계는 마이크로서비스 간의 효율적인 통신을 위한 중요한 요소입니다. 리소스, 행위, 표현의 세 가지 구성 요소와 설계 원칙을 기반으로 REST API를 구축함으로써, 개발자는 명확하고 일관된 API를 제공할 수 있습니다.
핵심 포인트:

• RESTful한 URI 설계를 통한 직관적인 API 구조
• HTTP 메소드의 적절한 활용으로 명확한 의도 전달
• 무상태성과 멱등성 보장을 통한 안정적인 서비스 제공
• 캐시 가능성 활용으로 성능 최적화
• 일관된 응답 코드 사용으로 클라이언트 개발 편의성 향상

이러한 원칙을 적용하여 REST API를 설계하면, 확장 가능하고 유지보수하기 쉬운 애플리케이션을 개발할 수 있습니다.