REST API 네이밍 원칙

REST

REST 는 Representational State Transfer 의 약어로, 하이퍼미디어를 전송하는 방법에 대한 구조적 규칙이다.

하이퍼미디어를 구성하는 모든 자원(resource)을 이름으로 구분하여 해당 자원의 정보를 주고 받는 방법에 대한 모든 것을 의미 한다.

REST는 6가지의 원칙과 제약을 갖는다. RESTful 서비스 인터페이스는 이 6가지 원칙과 제약을 준수 해야 한다.

 

REST의 6가지 원칙

 

1.일관된 인터페이스

 - URI로 지정한 자원에 대한 조작을 통일되고 한정적인 인터페이스로 수행하는 구조적 스타일을 말한다.

 

2.클라이언트-서버

 - 자원를 제공하는 쪽이 서버, 자원을 요청 하는 쪽을 클라이언트라 한다. 이 둘은 독립적으로 분리되어 구성되어야 한다. 각각 별도로 개발되고 대체 가능하도록 유지 해야 한다.

 

3.무상태(Stateless)

 - 작업에 대한 요청의 상태 정보를 저장하거나 관리 하지 않는다. 세션, 인증, 쿠키 등의 정보는 별도로 저장하기 때문에 요청에 대한 어떠한 상태 정보를 저장하지 않고 단순 처리할 수 있어야 한다. 이를 위해 모든 요청에는 필요한 모든 정보가 포함되어야 한다.

 

4.캐시의 기능

 - 서버는 캐시 가능 여부를 제공해야 한다. 캐시가 가능 할 경우 클라이언트는 응답 데이터를 재 사용 하여 성능과 서버의 가용성을 올릴 수 있다.

 

5.계층화된 시스템

 - 계층화된 구조로 구성되어야 한다. 각 계층 자신이 통신하는 컴포넌트 외 다른 계층에 대한 정보를 얻을 수 없도록 분리되어야 한다.

 

6.주문형 코드

 - 클라이언트는 서버로부터 실행시킬 수 있는 로직을 다운 받아 기능을 확장시킬 수 있다. 이를 통해 클라이언트가 사전에 구현해야 하는 기능의 수를 줄여 간소화 시킬 수 있다.

 

 

REST API는 URI를 이용하여 자원을 가리키고 자원에 접근할수 있게 만들어 클라이언트에게 제공해야한다.모호성을 최소화하고 가독성, 유지관리성을 극대화 할 수 있게 자원을 구분지어 명명하고, 일관된 형식을 사용하도록 한다.

 

 

자원을 명사로 나타낸다

 

RESTful URL가 가리키는 자원은 객체이다. 그러므로 동사가 아닌 명사로 칭한다.

 자원은 4가지 범주로 분류 할 수 있다.(문서(Document), 컬렉션(Collection), 스토어(Store), 컨트롤(Controll)) 자원이 어떤 범주에 속하는지 에 따라 일관된 네이밍을 사용 한다.

 

1. 문서

문서 자원은 DB의 하나의 레코드, 하나의 객체 인스턴스와 유사한 단일 자원의 개념이다. 단수를 사용 하여 문서 자원을 표현한다.

 

2. 컬렉션

서버가 관리하는 리소스 디렉터리이다. 클라이언트에 의해 새로운 리소스 추가가 요청 될 수 있다.(POST사용) 복수를 사용 하여 컬렉션 자원을 표현한다.

 

3. 스토어

스토어는 클라이언트가 관리 하는 자원 저장소이다. 클라이언트는 API를 이용하여 자원을 넣거나 가져올 수 있고 삭제 할 수 있다. 복수를 사용하여 스토어를 표현한다.

 

4. 컨트롤러
컨트롤러 자원은 인자와 반환 값, 입력 및 출력이 있는 실행 가능한 함수와 같다. 문서, 컬렉션, 스토어로 해결이 어려운 절차적 실행을 수행하기 위한 모델이다. 특정 자원을 가리키는 것이 아니라 실행 인 만큼 예외적으로 동사를 사용한다.

 

계층 관계를 나타내기 위해 ‘/’ 를 사용한다

자원 간의 계층 관계를 표현하기 위해 URI경로에 ‘/’를 사용 한다.

 

URI의 마지막에 ‘/’를 사용 하지 않는다.

URI의 마지막에 ‘/’를 사용 할 경우 혼동을 줄 수 있으므로 사용하지 않는다.

 

‘-’(하이픈)을 사용하여 가독성을 높인다.

긴 경로 이름에 ‘-’(하이픈)을 사용 하면 가독성을 높일수 있으며, 사람들이 쉽게 인식하고 해석 할 수 있게 도움을 준다.

 

‘_’(언더스코어)는 사용하지 않는다.

어플리케이션의 폰트에 따라, 일부 브라우저에서 ‘-’(언더스코어)는 불명확하게 표현되거나 보이지 않을 수 있다.

 

소문자를 사용 한다.

URI에 일관되게 소문자를 사용하도록 한다.
Schem, HOST는 대소문가 구분이 없으나 이외에는 모두 대소문자가 구분된다. 아래 예시에서 1번과 2번은 동일 하지만 3번은 다르다.

 

파일의 확장자는 사용하지 않는다.

파일 확장자는 가독성을 해치고 어떤 이점도 존재 하지 않는다. 파일 확장자를 제거 하여 URI의 길이를 줄이는 것이 더 좋다.
만약 자원의 유형을 강조 해야 할 필요가 있다면 Content-Type 헤더를 이용하는 방법을 활용 할 수 있다.

 

CRUD함수 명을 사용하지 않는다.

URI는 자원을 가리키는 것이다. 어떤 동작을 가리켜서는 안된다. CRUD는 HTTP의 요청 메소드를 이용하여 표현 할 수 있다.

 

자원의 필터링을 위해서는 쿼리 파라미터를 사용한다.

자원을 정렬, 필터링 하거나 제한된 수량을 요청 해야 할 필요가 있다. 이때 신규 API를 생성 하려 하지 말고 쿼리 파라미터를 활용 한다.

 

 

이번에 URI 정하는데 조금 더 공부가 필요하여 다시 공부해서 정리했다. 항상 완벽하게 지킬순 없겠지만 최대한 맞게 지켜서 누가 봐도 이해하기 편한 URI 작성이 되도록 노력해야겠다.