REST API 디자인 가이드의 적용

Project/커뮤니티 2023. 7. 18. 22:18

REST API 디자인 가이드의 적용

목차
1. 현재 API 상태
2. REST API란?
3. REST API의 구성 및 특징
4. REST API 디자인 가이드
5. REST API 디자인 가이드 적용 결과

현재 API 상태

목적	METHOD	PATH
유저 정보 조회	GET	/user/getinfo
전체 게시물 조회		/boards
단일 게시물 조회		/board/{:boardId}
게시물 페이징		/board/post?page=1&size=30&category='유머'
베스트 게시물		/board/best-post?page=0&size=20&category=humor&searchKeyword=null
게시물 검색결과		/board/search?page=1&size=20&searchTerm="term"
댓글 불러오기		/board/{:boardId}/comment
이메일 인증코드 생성		/auth/generateCode
회원가입	POST	/auth/register
아이디 중복확인		/auth/checkUid
닉네임 중복확인		/auth/checkNick
이메일 인증코드 확인		/auth/verifyCode
로그인		/auth/authenticate
자동로그인		/auth/silentRefresh
로그아웃		/auth/logout
게시물 등록		/board/register
게시물 수정		/board/update?id=' '
게시물 삭제		/board/delete?id=' '
게시물 추천/비추천		/board/recommend/{:boardId}
게시물 조회수 증가		/board/view
댓글 등록		/board/{:boardId}/comment
댓글 수정		/board/{:boardId}/comment/edit/{:commentId}
댓글 삭제		/board/{:boardId}/comment/delete/{:commentId}

위는 현재 제작중인 커뮤니티 사이트에서의 클라이언트-서버 간 통신에 사용되는 url path입니다. 이번 글에선 위 api path를 RESTful api 가이드 라인에 맞추어 수정해 보려 합니다.

REST API란?

수정에 앞서 REST api란 무엇일까 짚고 넘어가겠습니다. REST란 소프트웨어 아키텍처 스타일이며 HTTP 프로토콜을 의도에 맞게 활용하기 위해 제시된 제약사항입니다. REST의 원칙은 서비스에 대한 설명과 이해를 보다 쉽게 도우며, REST의 규칙을 준수해가며 만든 서비스를 RESTful하다고 할 수 있습니다.

REST API의 구성 및 특징

REST API는 자원(URL), 행위(Http Method), 표현으로 구성됩니다. 즉, REST에서는 자원을 URL로 표현하고 표현 대상이 되는 자원에서의 행할 행위를 HTTP Mehod로 정의해 표현합니다. 결과적으로 각각의 엔드포인트 자원을 표현하는 URL에 가지며 Method로 표현되는 행위를 처리합니다.

REST API는 아래와 같은 특징/제한조건을 갖습니다.

인터페이스의 일관성(Uniform interface) : URL에 대응하는 리소스에 대한 행위가 일관적인 인터페이스로 분리 된 아키텍처 스타일을 가진다.
무상태(Stateless) : 각 요청 간 클라이언트의 콘텍스트가 서버에 저장되지 않는다. 즉, 서버에서는 들어오는 요청에 대한 단순 처리만 수행하며 작업에 대한 정보를 따로 저장/관리 하지 않는다.
캐시 처리 가능(Cacheable) : 클라이언트는 response를 캐싱할 수 있어야 하며, 이를 통해 클라이언트 - 서버 간 상호작용을 최적화한다.
계층화 (Layered System) : 다중 계층 구조를 가질 수 있으며, 보안, 로드밸런싱, 암호화 계층 및 PROXY, 게이트웨이 등 중간매체를 사용할 수 있다.
클라이언트 - 서버 구조 : 아키텍처를 단순화시키고 작은단위로 분리해 클라이언트 및 서버의 역할을 확실히 구분해 상호 의존성을 줄이고 독립적으로 개선 가능하도록 한다.
자체 표현 구조 : REST API는 각 메시지가 자신을 어떻게 처리해야 되는지에 대한 충분한 정보를 포함해야 한다.즉, 메시지 자체를 통해 구체적인 미디어 타입, 처리방법, 버정 등을 알 수 있어야 한다.

REST API 디자인 가이드

REST API 디자인 가이드에서 가장 중심이 되는 규칙은 아래 두 가지입니다.

URL은 정보의 자원을 표현한다
자원에 대한 행위는 GET, POST, PUT, PATCH, DELETE 등 HTTP Method를 통해 표현한다.

Method	action
GET	리소스 조회
POST	리소스 생성
PUT	리소스 전체 수정
PATCH	리소스 부분 수정
DELETE	리소스 삭제

example)

내용	잘못된 예시	비고	올바른 예시
게시물 조회	GET /post/get/1	행위에 대한 표현은 method로 이용한다	GET /post/1
게시물 추가	GET /post/insert/2	행위에 대한 표현은 method를 이용한다. 행위에 대응하는 method를 사용한다.	POST /post or POST /post/1

참고사항)

'/' 구분자를 통해 계층구조를 나타낸다
URL 마지막에 '/'를 포함하지 않는다
소문자를 사용하며 가독성을 위해 밑줄(_) 대신 하이픈(-)을 사용한다.
파일 확장자는 header를 이용해 표현한다
적절한 상태코드를 반환해 요청의 성공, 실패, 리소스 상태등을 나타낸다 2XX(성공), 4XX(클라이언트에러), 5XX(서버에러)
Accept 필드와 Content-Type 필드를 통해 적절한 데이터 형식을 나타낸다.

REST API 디자인 가이드 적용 결과

목적	Method	PATH	query string or payload
회원가입	POST	/auth/register	{uid, nick, email, pwd}
회원가입	POST	/user	{uid, nick, email, pwd}
회원정보수정	-	-	-
회원정보수정	PATCH	/user	{edited}
회원정보조회	GET	/user/getinfo	-
회원정보조회	GET	/user	-
회원탈퇴	-	-	-
회원탈퇴	DELETE	/user	-
아이디 중복확인	POST	/auth/checkUid	{uid}
아이디 중복확인	POST	/user/check-uid	{uid}
닉네임 중복확인	POST	/auth/checkNick	{nick}
닉네임 중복확인	POST	/user/check-nick	{nick}
이메일 인증코드 생성	GET	/auth/generateCode
이메일 인증코드 생성	GET	/auth/email-authcode
이메일 인증코드 확인	POST	/auth/verifyCode	{authcode}
이메일 인증코드 확인	POST	/auth/email-authcode	{authcode}
로그인	POST	/auth/authenticate	{id, pwd}
로그인	POST	/auth/login	{id, pwd}
토큰 갱신	POST	/auth/silentRefresh
토큰 갱신	POST	/auth/renew-token
로그아웃	POST	/auth/logout	null
로그아웃	GET	/auth/logout
게시물 등록	POST	/board/register	{title, content}
게시물 등록	POST	/board/post	{title, content}
게시물 수정	POST	/board/update?id=' '	{title, content}
게시물 수정	PATCH	/board/post/{post-id}	{title, content}
게시물 삭제	POST	/board/delete?id=' '
게시물 삭제	DELETE	/board/post/{post-id}
단일 게시물 조회	GET	/board/{boardId}
단일 게시물 조회	GET	/board/post/{post-id}
전체 게시물 조회	GET	/boards
전체 게시물 조회	GET	/board
게시물 페이징	GET	/board/post	{page, size, category}
게시물 페이징	GET	/board/posts/{category}	{page, size}
베스트 게시물	GET	/board/best-post	{page, size, category, searchKeyword}
베스트 게시물	GET	/board/posts/best	{page, size}
게시물 검색결과	GET	/board/search	{page, size, searchTerm}
게시물 검색결과	GET	/board/posts/search	{page, size, searchTerm}
게시물 추천/비추천	POST	/board/recommend/{:boardId}	{recommendations}
게시물 추천/비추천	PATCH	/board/post/{post-id}/recommend	{recommendations}
게시물 조회수 증가	POST	/board/view
게시물 조회수 증가	PATCH	/board/post/{post-id}/view
댓글 불러오기	GET	/board/{:boardId}/comment
댓글 불러오기	GET	/board/post/{post-id}/comments
댓글 등록	POST	/board/{:boardId}/comment	{content}
댓글 등록	POST	/board/post/{post-id}/comment	{content}
댓글 수정	POST	/board/{:boardId}/comment/edit/{:commentId}	{content}
댓글 수정	PATCH	/board/post/{post-id}/comment/{comment-id}	{content}
댓글 삭제	POST	/board/{:boardId}/comment/delete/{:commentId}
댓글 삭제	DELETE	/board/post/{post-id}/comment/{comment-id}

REST API 디자인 가이드라인에 따라 기존 URL을 최대한 Method를 통해 행위를 표현하도록 수정하였습니다. login, logout 등과 같이 URL의 엔드포인트에서 자원을 직접적으로 수정하는 것이 아닌 특정 행위 자체를 표현하는 경우 해당 행위를 최대한 URL를 통해 직관적으로 파악할 수 있도록 했습니다.

HTTP 상태 코드 정리

RESTful API에서는 행위에 대한 결과를 HTTP 상태코드로 반환합니다. 주요 결과에 대한 상태 코드는 아래 표와 같습니다.

성공)

코드	내용
200	OK
201	Created - 요청에 성공 후 새로운 리소스 생성
202	Accepted - 클라이언트의 요청을 받은 후 아직 처리하지 않은 경우(비동기), 작업 완료 후 클라이언트가 해당 작업의 진행 상황을 파악할 수 있도록 URL을 links 필드를 통해 반환한다.

클라이언트 에러)

코드	내용
400	Bad request - 요청이 미리 정의해둔 파라미터를 위반한 경우
401	Unauthorized
403	Forbidden - 접근이 허용되지 않은 자원에 대한 접근
404	Not found
405	Method Not Allowed