REST API란?
REST API란, REST(Representational state transfer) 아키텍처 스타일의 설계 원칙을 준수하는 API(애플리케이션프로그래밍 인터페이스)이다.
REST 아키텍처에는 6가지 설계 원칙이 존재한다.
1. Uniform interface, 균일한 인터페이스
첫 번째는 균일한 인터페이스로, 동일한 리소스에 대한 모든 API 요청은 요청의 출처에 관계없이 동일하게 표시되어야 한다는 의미이다.
일관된 인터페이스를 얻기 위해서 다음과 같은 4가지 인터페이스 규칙이 존재한다.
identification of resources: 요청 시 개별 자원을 식별할 수 있어야 한다.
manipulation of resources through representations: 어떤 자원에을 변경하기 위해선 그 자원에 대해 작업하기 위한 표현과 메타데이터를 가지고 있어야한다.
self-descriptive messages: 자신을 어떻게 처리해야하는지 정보를 포함해야 한다.
hypermedia as the engine of application state: 단순히 결과 뿐만이 아니라 결과에 대한 정보도 포함해야 한다.
2. Client–server 구조, 클라이언트와 서버의 분리
두 번째는 클라이언트와 서버의 분리이다. 서로 완전히 독립적이어야 하고 클라이언트가 알아야하는 유일한 정보는 요청된 리소스의 URL 정보이다. 서버는 요청된 데이터를 클라이언트에게 전달하는 것 외에는 클라이언트 애플리케이션을 수정할 수 없다.
3. Stateless, 무상태성
세 번째는 무상태성이다. REST API는 무상태성이기 때문에 요청 처리에 필요한 모든 정보가 포함되어야 하고, 서버는 클라이언트 요청과 관련된 데이터를 저장할 수 없다. 즉, 세션이 필요없다.
4. Cacheable, 캐시 가능성
네 번째는 캐시 가능성이다. 가능한 경우 클라이언트나 서버 측에서 리소스를 캐시함으로써 클라이언트 측의 성능을 높이고, 서버측의 확장성을 높이는 것이다.
5. Layered system, 계층화된 시스템 아키텍처
다섯 번째는 계층화된 시스템 아키텍처이다. 클라이언트와 서버가 직접 연결되지 않고, 다양한 중개자를 통해 요청과 응답이 처리되도록 설계하는 것을 의미한다.
중개자는 캐싱, 로드밸런싱, 인증 등 다양한 역할을 수행할 수 있으며, 시스템의 보안과 확장성을 향상시킨다.
6. Code on demand (선택 사항)
마지막은 코드 온디맨드로, 서버가 클라이언트에서 실행시킬 수 있는 로직을 전송하여 클라이언트의 기능을 확장시키는 것을 의미한다.
REST API 네이밍 컨벤션
REST API 네이밍 컨벤션으로는 우선 자원은 명사로 나타내야하며, 계층 관계는 URI 경로에 '/'를 사용하여 표현한다.
URI 마지막에는 '/'를 사용하지 않으며, 단어 구분에는 -(하이픈)을 사용해서 가독성을 높인다. (언더스코어 _는 사용하지 않음)
그리고 일관되게 소문자를 사용하며, 파일의 확장자는 사용하지 않고, 동작을 나타내는 CRUD 함수명을 사용하지 않는다. (대신 HTTP 요청 메서드를 사용)
마지막으로 자원의 필터링을 위해서는 쿼리 파라미터를 사용한다.
🌟 추가 질문
📍 URI 경로 중 v1, v2는 어떤 경우에 사용하는 것일까?
v1, v2 등의 버전 표기 방법은 주로 API의 버전 관리를 위해 사용된다.
새로운 기능이 추가되거나, 성능 개선 및 버그 수정, API의 사용 방법이나 응답 형식이 변경된 경우 새로운 버전으로 API가 만들어질 수 있다.
그리고 기존 버전을 사용하던 클라이언트의 호환성을 위해 새로운 버전이 나오더라도 기존 버전을 유지하면서 제공할 수 있다.
하지만 그렇게 되면 중복된 기능이 2개 존재한다는 것이고 유지 보수 비용도 2배로 늘 것이다. 그래서 충분히 공지를 한 다음 일정 기간을 갖고 없애는 방법이 있고, 혹은 API 사용량을 보고 결정하는 방법도 있다.
결론은 v1, v2와 같은 버전 표기는 API 및 URI 변경과 호환성을 관리하는 수단으로, 이를 통해 새로운 기능을 쉽게 추가하고, 기존의 클라이언트를 보호할 수 있다.
참고 자료
REST API란 무엇인가요?
RESTful API를 위한 6가지 원칙과 네이밍
RESTful API 네이밍
