여기서 나는 REST API에 대해서 모든 것을 다루지 않았으며, 풀 스택으로 프로젝트를 진행하면서 느낀 꼭 필요한 만큼의 REST API를 정리했다.
REST API를 깊게 이해하고 싶다면, 여기를 추천한다.
REST API Design Tutorial | restfulapi.net
REST란
REST란 REpresentational State Transfer의 약자이다. (번역하면 '표시적인 상태 전달') 즉, 명시적으로 상태를 표시하여 서버-클라이언트간 데이터를 송수신하는 방식 정도로 풀이할 수 있다.
RESTful API란 connection-less, state-less한 HTTP 특성을 극복하기 위해, 클라이언트와 서버가 데이터를 주고 받을 때 상태를 표시하여 맥락을 이해할 수 있도록 고안된 API 포맷을 말한다.
문법이 아니기 때문에 개인 프로젝트에서는 유연하게 사용해도 되지만, 다수의 개발자들 간 약속된 형식이 존재하기 때문에 협업 시에는 API 문서를 작성하여 철저하게 지키도록 요구된다.
클라이언트
클라이언트는 서버의 리소스를 명시적으로 읽고 쓰기 위해, 요청 시 GET, POST, PUT, PATCH, DELETE 등 메소드를 붙여 어떤 액션(Action)임을 명시한다.
POST // Create
GET // Read
PUT // Replace
PATCH // Update
DELETE // Delete서버
서버에서는 클라이언트 요청을 핸들링하고, 처리 결과가 어떤 상태임을 Indicate(명시) 해주기 위해 Status 코드를 붙여 응답한다.
2XX - 클라이언트 요청 성공 시
200 Success // 요청이 잘 처리되었을 경우
201 Created // 요청이 잘 처리 되었고, 새로운 자원이 생성되었을 경우
204 No Content // 요청이 잘 처리 되었으나, 응답할 자원이 없을 경우4XX - 클라이언트 요청 에러 시
400 Bad Request // 잘못된 양식(문법)의 요청일 경우
401 Unauthorized // 요청에 인증에 필요한 데이터가 없을 경우
403 Forbidden // 인증은 되었으나, 어떤 사유로 해당 사용자에 대해 리소스 접근이 금지되었을 경우
404 Not found // 조회할 리소스가 서버에 없는 경우
409 Conflict // POST 메소드로 서버에 리소스 추가를 요청했을 때, 이미 그 자원이 서버에 있어서 자원을 추가할 수 없는 경우.
422 Unprocessable Entity // 양식은 맞으나, 서버 내부 로직(주로 유효성 검사 로직)상 값이 유효하지 않아 요청을 처리할 수 없는 경우5XX - 서버 응답 에러
500 Internal Server Error // 서버에서 응답 처리 중 발생한 에러 (요청이 잘못된 것이 아님)
503 Service Unavailable // 서버가 현재 요청을 처리할 수 없는 상태API 엔드포인트
resource URIs are endpoints for RESTful services.
참고 : REST Resource Naming Guide | restfulapi.net
엔드포인트 작성시, 리소스의 맥락을 누구나 파악할 수 있게 URI(Uniform Resouce Indicator)를 구조적으로 쓰는 것이 좋다. 나는 구체적으로 다음과 같이 데이터 모델을 파악할 수 있는 컨벤션을 사용한다.
실제 DB 리소스를 응답하는 요청 일 경우
// NOSQL(MongoDB)
METHOD /collection/(:document_id)
// SQL(MySQL)
METHOD /table_name/(:row_id)
// Example
POST /users // Create user (가입)
DELETE /users/:user_id // Delete target user (탈퇴)
GET /posts // Retreive all posts
GET /posts/:post_id // Retreive target post
POST /posts // Create post
PATCH /posts/:post_id // Update target post
DELETE /posts/:post_id // Delete target post
GET /users/:user_id/posts // Get target user's posts (join 쿼리 사용) 인증과 관련된 요청 일 경우
로그인 및 로그아웃은 실제 DB 리소스를 변경하는 게 아니라, 로그인된 상태 즉, 세션(Session)을 생성하고 파괴하는 개념이므로 나는 다음과 같이 특수하게 엔드포인트를 만든다.
(인증에 세션을 사용하든 토큰을 이용하든 맥락 이해를 할 수 있게 만들어 주면 된다)
예시를 보자. 다음은 RESTful하지 않은 엔드포인트이다.
POST /login
POST /logout로그인과 로그아웃은 사용자의 액션(action)이 동반되는 동사(Verb)이고, 특히 로그아웃은 무언가를 생성하는 개념이 아니므로 메서드와 엔드포인트를 수정할 필요가 있다.
그래서 나는 권한(authority) 데이터가 생성되고 삭제되는 관점으로 바꿨고, 다음과 같이 수정했다.
POST /auth // Create user authoriy
DELETE /auth // Delete user authority