[코드리뷰] 07.01(1) REST와 endpoint 명명 팁

 
 
 
1. endpoint 수정

단수형에서 복수형으로 표현을 바꾼 경우 RESTful* 디자인 원칙을 준수한 것으로 볼 수 있다.
디자인의 일관성을 높이는 방법이다.
 
*REST (Representational State Transfer)
소프트웨어 아키텍쳐 스타일 중 하나
웹 서비스 개발을 위한 일련의 제약 조건과 원칙을 정의한다.
일관된 인터페이스를 유지하고, HTTP 메서드와 URI를 이용해 자원에 접근하는 방식으로 시스템을 설계한다.
 
RESTful 은 REST 원칙을 따른 설계 시스템이나 웹 서비스, 그리고 이들이 제공하는 API을 표현하는 형용사이다.
REST의 제약 조건을 준수함으로써 확장성, 성능, 유지보수성이 향상된다.
 
<REST 주요 원칙>

• 클라이언트-서버 구조: 클라이언트와 서버는 독립적으로 동작하며 서로의 구현에 대해 알 필요가 없다.
• 무상태(Stateless): 각 요청은 독립적이고 자급자족한다. 서버는 클라이언트의 상태를 저장하지 않는다.
• 캐시 가능(Cacheable): 응답은 명시적으로 캐시 가능 또는 불가로 표시되어야 한다.
• 통일된 인터페이스(Uniform Interface): 일관된 방식으로 리소스를 접근하며, 주로 HTTP 표준 메서드(GET, POST, PUT, DELETE 등)를 사용한다.
• 계층화 시스템(Layered System): 클라이언트는 중개 서버를 통해서 리소스에 접근할 수 있고 중개 서버는 여러 계층으로 구성될 수 있다.
• 코드 온 디맨드(Code on Demand, 선택적): 서버는 클라이언트에 스크립트를 제공하여 실행할 수 있다. 예를 들어 JavaScript 코드가 있다.

endpoint는 자원의 "집합"을 나타내므로 애초에 복수형을 사용해야 한다.
 
의미를 명확하게 전달할 수 있다.
내부 메서드를 살펴보면 POST 요청으로 하나의 memo(article)를 등록하고, GET 요청으로 전체 memo(article)들의 목록을 read하고 있는데, 해당 endpoint에서는 memo를 1개 등록하는 작업과 등록된 memo를 여러 개 조회하는 작업이 이루어지기에 "메모들"로 보아야 한다. 1개의 memo를 등록하는 작업 역시, 그 결과는 컬렉션에 추가되므로 복수형이 되어야 한다. 그러니 memo라고만 하면 전체 요청을 포괄하는 의미가 아니다. 여러 메모를 다루므로 복수형 memos로 사용해야 좋다.
 
다음과 같은 예시를 들 수 있다.

 

• GET /memos : 모든 메모를 가져옴
• POST /memos : 새로운 메모를 생성함
• GET /memos/{id} : 특정 메모를 가져옴
• PUT /memos/{id} : 특정 메모를 수정함
• DELETE /memos/{id} : 특정 메모를 삭제함

 

memo에서 memos로 쓴다면 변경사항이 발생할 경우 설계한 API에 대한 해당 표현이 의미와 일치하는지 따져보는 과정에서 하나하나 바꿔야하는 수고로움을 덜 수 있다. API 설계는 서버와 클라이언트간의 결합을 최소화하여 쉽게 바꿀 수 있도록 이루어진 것이 효과적인 설계라고 보아야 한다. 복수형 엔드포인트는 새로운 기능 추가시에도 단수형보다 자연스럽게 확장이 가능하다.
 
 

---