[Software Architecture] REST API과 RESTful API

REST API의 개념

• REST(Representational State Transfer) 원칙을 기반으로 만들어진 API
• 웹의 기존 기술과 HTTP 프로토콜을 활용한 소프트웨어 아키텍처 스타일로 자원의 상태 정보를 주고받는 방식
• HTTP URI를 통해 자원을 식별하고, HTTP 메서드를 통해 해당 자원을 처리
  • HTTP 메서드 : GET, POST, PUT, DELETE

RESTful API의 개념

• REST 원칙을 엄격히 준수하여 설계된 API를 의미
• REST의 이상적이고 완전한 구현을 뜻하며 자원 중심 설계와 HTTP 프로토콜의 올바른 사용을 강조
• 일관성, 가독성, 유연성을 제공하여 개발자 경험과 시스템의 유지보수성을 높임

---

RESTful API가 각광받는 이유

멀티플랫폼 지원

• IoT, 모바일, 태블릿, 웹 브라우저 등 다양한 클라이언트에서 데이터를 소비하는 시대가 되었기 때문에 일관된 데이터 포맷(주로 JSON)을 반환하는 RESTful API는 여러 디바이스 간의 통신을 간단하게 만듦
• HTML이나 JSP 같은 포맷은 웹 브라우저에 특화되어 있어 다른 디바이스에서는 추가적인 데이터 변환 작업이 필요
• 반면, JSON과 같은 경량 데이터 형식은 플랫폼 독립적이고, 각 디바이스가 필요한 형태로 데이터를 처리 가능

IoT와의 통합

• IoT 디바이스(로봇청소기, 세탁기, 냉장고 등)는 서버로부터 명령을 받고 데이터를 보내야 하는데, RESTful API는 경량화된 프로토콜과 JSON 기반 통신을 통해 이러한 디바이스들과 쉽게 통합
• IoT 환경에서는 서버와 클라이언트가 독립적이어야 하므로 상태를 유지하지 않는 Stateless 설계가 유리

웹, 모바일, 데스크톱 간의 코드 중복 방지

• 기존의 JSP나 HTML 중심의 서버 렌더링 방식은 브라우저에서 동작하도록 설계된 경우가 많음
• 모바일 앱이나 데스크톱 앱에서는 같은 데이터를 처리하기 위해 별도의 구현이 필요
• RESTful API는 데이터를 반환하고 클라이언트가 이를 처리하도록 위임하므로, 서버 코드의 재사용성과 유지보수성이 높아짐

클라이언트-서버 구조의 명확한 분리

• RESTful API는 서버는 데이터를 제공하고 클라이언트는 데이터를 소비하는 역할로 명확히 분리
• 이는 각자의 책임을 분리하고 독립적으로 개발 및 유지보수가 가능
  Ex) 동일한 RESTful API를 웹, 모바일, 또는 IoT 디바이스에서 사용 가능

가벼운 데이터 교환 포맷(JSON)

• RESTful API는 JSON과 같은 경량 데이터 포맷을 주로 사용하여 클라이언트와 서버 간의 데이터 교환이 효율적
• HTML, XML에 비해 데이터 크기가 작고 처리 속도가 빠르며, 대부분의 프로그래밍 언어에서 쉽게 파싱 가능

API 확장성과 유연성

• RESTful API는 버전 관리와 자원 기반 설계로 인해 새로운 기능을 추가하거나 확장이 용이
  Ex) /api/v1/devices → /api/v2/devices로 확장하면서도 기존 클라이언트를 지원 가능

---

RESTful API의 규칙

• 자원의 고유 식별
  • 모든 자원은 고유한 URI를 가져야 함
    Ex) /users/123는 ID 123인 사용자를 나타냄
• HTTP 메서드 활용
  • CRUD 작업은 HTTP 메서드를 통해 수행
    • POST : 자원 생성(Create)
    • GET : 자원 조회(Read)
    • PUT : 자원 수정(Update)
    • DELETE : 자원 삭제(Delete)
• Stateless 설계
  • 서버는 클라이언트의 상태를 저장하지 않음
  • 각 요청은 독립적이며 필요한 모든 정보를 포함
• 자원의 표현(Representation)
  • 자원은 JSON, XML 등으로 표현
  • 클라이언트와 서버는 데이터 포맷을 협상할 수 있어야 함
• 계층화된 시스템
  • 클라이언트는 서버의 내부 동작을 알 필요가 없으며 서버는 계층화된 구조를 가질 수 있음
• 캐싱 가능
  • 응답 데이터는 HTTP의 캐싱 메커니즘을 통해 캐싱될 수 있어야 함
• 일관성 있는 URI
  • URI는 자원을 식별하는 데만 사용하고 동작을 포함하지 않음
    • RESTful : /users/123
    • 비RESTful : /getUserById/123

---

RESTful API 설계 시 유의할 점

URI 설계

• 명사 중심으로 설계
  • URI는 자원을 나타내야 하며 동사를 포함해서는 안 됨
    /users, /orders/123 (RESTful)
    /getUser, /deleteOrder/123 (비RESTful)

 

HTTP 상태 코드

• 적절한 상태 코드를 반환
  • 200 OK : 요청 성공
  • 201 Created : 자원 생성 성공
  • 400 Bad Request : 잘못된 요청
  • 404 Not Found : 자원 없음
  • 500 Internal Server Error : 서버 오류

 

Stateless 원칙 준수

• 클라이언트의 상태를 서버에 저장하지 않도록 설계
• 모든 요청은 필요한 정보를 자체적으로 포함

 

버전 관리

• API가 변경될 경우를 대비하여 URI에 버전을 포함
  Ex) /v1/users, /v2/users

보안

• HTTPS를 사용하여 데이터를 암호화
• OAuth, JWT 등 인증 방식을 활용

효율적인 응답 설계

• 클라이언트의 요청에 따라 필요한 데이터만 반환하도록 설계
  Ex) 필터링, 페이징 등을 지원