REST API 설계 원리를 살펴보기 전에 REST API가 무엇인지 알아보는 것이 좋습니다.
REST(Representational State Transfer)는 웹 애플리케이션의 아키텍처 스타일이며, REST API는 이 아키텍처 스타일에 따라 구현된 API입니다.
REST API 디자인의 7가지 기본 원칙은 API 단순성, 클라이언트-서버 분리, 상태 비저장, 캐시 가능성, 계층화, 일관된 인터페이스 및 자체 설명 메시지입니다.
이러한 원칙을 따르면 유지 관리 및 확장이 더 용이한 API를 개발하는 데 도움이 됩니다.
아래 기사에서 자세히 알아보도록 하겠습니다.
REST API 디자인의 7가지 기본 원칙을 알아보세요.
1. API의 단순성
API는 필요한 기능을 간단하고 명확하게 제공해야 합니다.
사용자가 API를 쉽게 이해하고 사용할 수 있도록 복잡성을 최소화해야 합니다.
기능이나 옵션이 너무 많은 API는 사용자에게 혼란을 줄 수 있으므로 필요한 기능만 제공하는 것이 중요합니다.
강조점 1: 명확한 엔드포인트 디자인
API의 엔드포인트는 명확하게 설계되어야 합니다.
각 엔드포인트는 하나의 기능만 담당해야 하며 엔드포인트로 향하는 경로는 직관적이고 명확해야 합니다.
강조점 2: 필요한 매개변수만 요청
API 요청 시 꼭 필요한 파라미터만 요청하시기 바랍니다.
너무 많은 매개변수를 요청하면 사용자가 어떤 매개변수를 입력해야 하는지 혼동하게 됩니다.
필요한 매개변수만 요청하여 API 사용 편의성을 높여야 합니다.
2. 클라이언트-서버 분리
API의 클라이언트와 서버는 완전히 분리되어야 합니다.
클라이언트는 서버의 내부 구현에 대해 아무것도 알 필요가 없으며 서버는 클라이언트의 상태를 관리해서는 안 됩니다.
이를 통해 각자의 역할과 책임이 명확해지고, 서로 독립적으로 발전할 수 있게 됩니다.
강조점 1: 클라이언트와 서버의 독립성
클라이언트와 서버는 독립적으로 변경되어야 합니다.
서버의 내부 구현이 변경되더라도 클라이언트는 영향을 받지 않아야 합니다.
마찬가지로 클라이언트의 요구 사항이 변경되더라도 서버는 영향을 받지 않아야 합니다.
강조점 2: 계층 구조
API의 클라이언트-서버 구조는 계층적으로 구성되어야 합니다.
서버는 여러 계층으로 구성될 수 있으며 클라이언트는 계층 간의 통신에만 집중해야 합니다.
이를 통해 시스템의 확장성과 보안이 향상될 수 있습니다.
3. 무국적
REST API는 상태 비저장이어야 합니다.
즉, 서버는 클라이언트의 상태를 관리해서는 안 됩니다.
모든 요청은 그 자체로 완전한 정보를 포함해야 하며 이전 요청에 대한 응답을 대체해서는 안 됩니다.
이를 통해 서버의 확장성을 높일 수 있습니다.
강조점 1: 세션 상태 제거
API 요청 시 세션 상태를 사용하면 안 됩니다.
클라이언트의 모든 요청은 필요한 정보를 전달해야 하며, 서버는 이를 기반으로 적절한 응답을 제공해야 합니다.
세션 상태를 사용하면 서버의 확장성이 제한될 수 있으므로 피해야 합니다.
강조점 2: 인증 및 인증
API 요청 시 인증 및 승인을 통해 보안을 관리해야 합니다.
클라이언트는 요청에 필요한 정보를 포함해야 하며, 인증 및 권한 부여 후에 서버는 클라이언트의 요청을 처리해야 합니다.
4. 캐시 가능성
REST API는 캐시 가능해야 합니다.
클라이언트가 응답을 캐시할 수 있도록 서버는 응답에 캐시 헤더를 포함해야 합니다.
이렇게 하면 네트워크 대기 시간을 줄이고 서버의 로드를 줄일 수 있습니다.
하이라이트 1: 캐시 헤더 추가
클라이언트가 응답을 캐시할 수 있도록 API 응답에 캐시 헤더를 추가해야 합니다.
캐시 헤더는 응답의 유효 기간을 설정하거나 응답이 변경되지 않은 경우 클라이언트에 캐시를 사용하도록 지시할 수 있습니다.
강조점 2: 조건부 요청
클라이언트는 조건부 요청을 서버에 보낼 수 있어야 합니다.
요청할 때 이전에 캐시된 응답이 유효한지 확인하고, 그렇지 않은 경우에만 실제 서버로부터 응답을 받아야 합니다.
5. 계층화
REST API는 계층화되어야 합니다.
여러 계층으로 구성된 서버는 각 계층별로 역할과 책임이 명확하게 정의되어 있어야 합니다.
이를 통해 시스템의 유연성과 확장성이 향상됩니다.
강조점 1: 레이어 간 커뮤니케이션
API 계층 간에는 직접적인 통신이 있어서는 안 됩니다.
각 레이어는 자신의 위와 아래에 있는 레이어에 대해서만 알아야 하며 다른 레이어에 직접적인 종속성을 가져서는 안 됩니다.
강조점 2: 레이어 추가 및 삭제
API의 레이어는 필요에 따라 추가하거나 삭제할 수 있어야 합니다.
새로운 기능을 추가하거나 시스템을 확장할 때 새 레이어를 추가하거나 더 이상 필요하지 않은 레이어를 삭제할 수 있어야 합니다.
6. 일관된 인터페이스
REST API는 일관된 인터페이스를 제공해야 합니다.
API의 엔드포인트, HTTP 메서드, 응답 형식 등은 일관되게 설계되어야 하며 사용자가 쉽게 이해하고 사용할 수 있어야 합니다.
하이라이트 포인트 1: 명명 규칙
API의 엔드포인트, 매개변수, 응답 형식 등에 일관된 명명 규칙을 적용해야 합니다.
가독성과 이해도를 높여 사용자가 API를 더 쉽게 사용할 수 있도록 해야 합니다.
강조점 2: 오류 처리
API의 오류 처리는 일관되게 구현되어야 합니다.
오류 메시지와 HTTP 상태 코드의 형식은 특정 규정에 따라 정의되어야 하며 사용자가 오류를 쉽게 이해하고 대응할 수 있어야 합니다.
7. 자기 설명적 메시지
REST API는 자체 설명 메시지를 사용해야 합니다.
메시지에는 클라이언트가 API 응답을 이해하고 처리하기 위해 추가 문서나 자세한 설명을 참조할 필요가 없도록 필요한 모든 정보가 포함되어야 합니다.
강조점 1: 메시지 구조
API의 메시지 구조는 명확하고 일관되게 설계되어야 합니다.
클라이언트가 응답을 이해하고 처리할 수 있도록 필요한 정보가 메시지의 헤더나 본문에 포함되어야 합니다.
강조점 2: API 문서
API 문서는 API의 자체 설명 메시지를 구현하는 데 도움이 됩니다.
적절한 문서는 사용자가 API를 쉽게 이해하고 사용할 수 있도록 보장해야 합니다.
결론적으로
REST API 디자인의 7가지 기본 원칙을 배웠습니다.
이러한 원칙에 따라 API를 설계하면 사용자가 쉽게 이해하고 사용할 수 있는 효율적인 API를 구현할 수 있습니다.
간결한 API 디자인, 클라이언트-서버 분리, 무상태, 캐시 가능성, 계층화, 일관된 인터페이스 및 자체 설명 메시지를 적용하는 것이 API 디자인의 핵심입니다.
알아두면 유용한 추가 정보
API를 설계할 때 고려해야 할 보안 요소가 무엇인지 알아보세요. RESTful API의 기능에 대해 자세히 알아보세요. API 요청 시 클라이언트가 사용할 수 있는 다양한 HTTP 메서드에 대해 알아보세요. API를 설계할 때 버전을 관리하는 방법을 알아보세요. API 성능을 향상시키는 다양한 방법에 대해 알아보세요.
당신이 놓칠 수 있는 것
API를 설계할 때 클라이언트와 서버 분리, 상태 비저장, 캐시 가능성과 같은 원칙을 간과할 수 있습니다.
또한 일관되지 않은 인터페이스, 계층 구조 부족, 메시징 부족도 주의해야 할 요소입니다.
이러한 사항을 염두에 두고 API를 설계하면 효율적이고 유지 관리하기 쉬운 API를 구현할 수 있습니다.