REST API
REST API
REST(Representational State Transfer)는 분산 하이퍼미디어 시스템을 위한 아키텍처 스타일입니다. 웹의 기존 기술과 HTTP 프로토콜을 최대한 활용하여 확장성, 단순성, 신뢰성 등을 높이는 것을 목표로 합니다. REST API는 이러한 REST 아키텍처 스타일의 제약 조건을 따르는 API를 의미합니다.
🏛️ REST의 6가지 제약 조건
1. 클라이언트-서버 (Client-Server) : 클라이언트와 서버의 역할이 명확히 분리되어 각각 독립적으로 발전할 수 있습니다. 2. 무상태성 (Stateless) : 서버는 클라이언트의 요청 간에 어떤 클라이언트 상태도 저장하지 않습니다. 각 요청은 필요한 모든 정보를 포함해야 합니다. (장점: 서버 확장성 용이, 서버 부담 감소) 3. 캐시 가능 (Cacheable) : 클라이언트는 응답을 캐시할 수 있어야 하며, 서버는 응답이 캐시 가능한지 명시해야 합니다. (장점: 응답 시간 단축, 서버 부하 감소) 4. 계층화된 시스템 (Layered System) : 클라이언트는 서버와 직접 통신하는지, 중간에 프록시, 로드 밸런서, 게이트웨이 등이 있는지 알 필요가 없습니다. 5. 코드 온 디맨드 (Code-On-Demand, Optional) : 서버가 클라이언트에 실행 가능한 코드(e.g., JavaScript)를 전송하여 클라이언트 기능을 확장할 수 있습니다. (선택 사항) 6. 인터페이스 일관성 (Uniform Interface) : REST의 핵심. 시스템 전체에 걸쳐 일관된 인터페이스를 제공합니다. > * 자원의 식별 : URI(Uniform Resource Identifier)를 사용하여 리소스를 식별합니다. (e.g., `/users/1`, `/products`) > * 메시지를 통한 리소스 조작 : HTTP 메서드(GET, POST, PUT, DELETE 등)를 사용하여 리소스를 조작합니다. > * 자기 서술적 메시지 : 메시지 자체에 필요한 모든 정보(미디어 타입, 상태 코드 등)를 포함하여 메시지만으로 이해 가능해야 합니다. > * 하이퍼미디어 (HATEOAS, Hypermedia As The Engine Of Application State) : 응답에 다음 가능한 상태 전이를 위한 링크를 포함합니다. (REST의 이상적인 형태)
🛠️ REST API 설계 원칙
- URI는 리소스를 표현해야 한다 : 동사보다는 명사를 사용하고, 복수형을 사용하는 것이 일반적입니다. (e.g., `/users` 대신 `/user`, `/getUser` 대신 `/users`)
- HTTP 메서드로 행위(CRUD)를 표현한다
> * `GET`: 리소스 조회 (멱등성, Idempotent) > * `POST`: 리소스 생성 (멱등성 X) > * `PUT`: 리소스 전체 수정 (멱등성) > * `PATCH`: 리소스 부분 수정 (멱등성 X) > * `DELETE`: 리소스 삭제 (멱등성)
- 메시지는 자기 서술적이어야 한다 : HTTP 헤더(Content-Type, Accept 등)와 상태 코드(Status Code)를 적절히 사용하여 메시지 자체로 의미를 전달해야 합니다.
💡 개발자 핵심 Point
- REST API는 웹 서비스 개발의 사실상 표준으로 자리 잡았습니다.
- RESTful 하다 : REST의 제약 조건을 잘 지키는 API를 'RESTful 하다'고 표현합니다. 특히 '인터페이스 일관성'과 '무상태성'이 중요합니다.
- HATEOAS의 중요성 : REST의 가장 이상적인 형태이지만, 실제 구현에서는 복잡성 때문에 완전히 지켜지지 않는 경우가 많습니다. 하지만 REST의 철학을 이해하는 데 중요합니다.
- API 버전 관리 : API가 변경될 경우, 기존 클라이언트와의 호환성을 위해 버전 관리가 필요합니다. (e.g., URI에 버전 포함 `/v1/users`, 헤더에 버전 포함)
- API 문서화 : REST API는 자기 서술적이어야 하지만, 복잡한 비즈니스 로직이나 사용법을 명확히 전달하기 위해 Swagger/OpenAPI와 같은 도구를 사용하여 API 문서를 잘 작성하는 것이 중요합니다.
