마이크로 서비스 아키텍처(MSA) 프로젝트 설계 중 REST API 설계를 담당했습니다.
아무것도 모르는 상태였지만 여러 자료를 참고하여 작성했고, REST API 설계에 대한 피드백을 받을 때 잘 작성되었다는 평을 들었습니다.
좋은 피드백을 받은 RESTful API endpoints 작성하는 법에 대해 공유하려 합니다.
✍️ REST API 디자인 가이드
가장 중요한건 다음과 같다고 합니다.
첫 번째, URI는 정보의 리소스를 표현해야 한다.
두 번째, 리소스에 대한 행위는 HTTP Method(GET, POST, PUT, DELETE 등)로 표현한다.
REST API 중심 규칙
1) URI는 정보의 리소스를 표현해야 한다.
👎나쁜 예 (동사 기반 엔드포인트)
/getUsers,/createProduct,/updatePost,/deleteComment
👍좋은 예 (명사 기반 엔드포인트)
/users,/products,/posts,/comments
리소스는 API로 식별하고 조작할 수 있는 모든 (1)엔터티 입니다. 예를 들어 사용자, 제품, 게시물, 댓글 등은 모두 리소스입니다. 이러한 리소스를 노출하는 엔드포인트의 이름을 지정하려면 해당 리소스를 명확하고 간결하게 설명하는 명사를 사용해야 합니다.
그리고 컬렉션을 표시하려면 명사의 복수형으로 작성해야합니다. 컬렉션은 동일한 유형의 리소스 그룹입니다. 예를 들어 /users는 사용자 리소스의 컬렉션이고, /posts는 게시물 리소스의 컬렉션입니다.
단일 리소스 표현 (단수형 명사)
/user, /product, /post, /comment
리소스 그룹 표현 (복수형 명사)
/users, /products, /posts, /comments
2) 자원에 대한 행위는 HTTP Method(GET, POST, PUT, DELETE 등)로 표현한다.
POST, GET, PUT, DELETE 이 4가지의 Method를 가지고 CRUD를 할 수 있습니다.
- Create →
POST: POST를 통해 해당 리소스를 생성합니다. - Read →
GET: GET를 통해 해당 리소스를 조회합니다. - Update →
PUT: PUT를 통해 해당 리소스를 수정합니다. - Delete →
DELETE: DELETE를 통해 리소스를 삭제합니다.
그래서 URI가 행위를 제외하고 자원을 표현하는데 중점을 둘 수 있습니다.
게시물을 조회할 때 👀
❌ GET/posts/show/1
⭕ GET/posts/1
게시물을 추가할 때 ➕
❌ POST/posts/insert/2
⭕ POST/posts/2
URI 설계 시 주의할 점
1) 슬래시 구분자(/)는 계층 관계를 나타내는 데 사용한다.
관계는 일종의 연관성이나 종속성을 암시하는 2개 이상의 리소스 간의 연결입니다.
예를 들어 게시물에는 댓글이 많고 댓글은 게시물에 속합니다. 이러한 관계를 노출하는 엔드포인트의 이름을 정하려면 상위-하위 또는 소유자 소유 관계를 반영하는 계층 구조를 사용해야 합니다.
특정 게시물의 댓글을 표시하는 계층적 엔드포인트
❌/comments?postId={postId}
⭕/posts/{postId}/comments
2) URI 마지막에 슬래시(/)를 포함하지 않는다.
REST API는 분명한 URI를 만들어 통신을 해야 하기 때문에 혼동을 주지 않도록 URI 경로의 마지막에는 슬래시(/)를 사용하지 않습니다.
❌
http://restapi.example.com/sports/soccer/
⭕http://restapi.example.com/sports/soccer
3) 밑줄(_)말고 하이픈(-)으로 URI 가독성을 높이는데 사용한다.
불가피하게 긴 URI경로를 사용하게 된다면 하이픈을 사용해 가독성을 높일 수 있습니다. 밑줄은 보기 어렵거나 밑줄 때문에 문자가 가려질 수도 있는 이유때문에 사용하지 않습니다.
❌
/products/electronics/computer_accessories
⭕/products/electronics/computer-accessories
4) URI 경로는 소문자로 작성
URI 경로에 대문자 사용은 피하도록 해야 합니다. 대소문자에 따라 다른 리소스로 인식하게 되기 때문입니다. ← RFC 3986(URI 문법 형식) 규정
5) 매개변수를 사용하여 필터링, 정렬, 페이지 매기기
매개변수는 엔드포인트의 동작이나 출력을 수정하는 키-값 쌍입니다. 예를 들어 쿼리 매개 변수를 사용하여 컬렉션 엔드포인트의 결과를 필터링, 정렬 또는 페이지네이션을 할 수 있습니다.
매개 변수의 이름을 지정하려면 매개 변수의 목적과 기능을 나타내는 설명적이고 일관된 이름을 사용해야 합니다. 예를 들어 /users?name=John&age=25&sort=asc&page=2는 이름과 나이를 기준으로 사용자를 필터링하고 오름차순으로 정렬한 후 결과의 두 번째 페이지를 반환하는 매개변수화된 엔드포인트의 좋은 예입니다. /users?q=John&f=25&o=asc&l=2와 같이 매개변수의 의미가 모호하거나 효과를 설명하지 못하는 애매한 이름을 사용하지 마세요.
6) 작업을 수행하려면 동사를 사용
작업은 리소스나 컬렉션에 대해 일종의 비즈니스 로직이나 비CRUD 작업입니다. 예를 들어, 작업은 리소스 또는 컬렉션을 활성화, 비활성화, 승인, 거부 또는 전송하는 것일 수 있습니다. 이러한 작업을 수행하는 엔드포인트의 이름을 지정하려면 작업을 명확하고 정확하게 설명하는 동사를 사용해야 합니다. 이때 작업을 명확하게 표현하지 않는 명사나 형용사는 사용하지 마세요.
👎나쁜 예 (수행되는 작업을 나타내지 않는 명사 또는 형용사 기반 엔드포인트)
/users/{userId}/status,/products/{productId}/delivery,/posts/{postId}/status
👍좋은 예 (특정 리소스에 대한 작업을 수행하는 동사 기반 엔드포인트)
/users/{userId}/activate,/products/{productId}/send,/posts/{postId}/approve
🗒️ 용어 정리
(1)엔터티 : 엔터티는 사람, 장소, 물건, 사건, 개념등의 명사에 해당한다. 엔터티는 엄무상 관리가 필요한 관심사에 해당한다. 엔터티는 저장이 되기 위한 어떤 것(thing)이다.
