REST API란 REST 아키텍처에 맞게 설계한 API를 말하며 REST 아키텍처는 단순한 url을 지향하고 HTTP method를 활용해 자원에 대한 API의 의도를 명확하게 표현하는 설계 방식을 뜻한다. REST API 작성 시 지켜야 하는 몇 가지 기본 규칙은 다음과 같이 정리할 수 있다.
- 리소스명은 동사 대신 명사를 사용한다.
- 리소스에 대한 행위, 동사에 해당하는 부분은 URL에 표현하지 않고 HTTP Method를 사용해 표현한다.
- 슬래시를 통해 계층 관계를 표현한다.
- 대문자 대신 소문자를 사용한다..
- 밑줄은 사용하지 않고 하이픈을 사용한다.
- 확장자는 사용하지 않는다.
- URL의 마지막에는 슬래시를 작성하지 않는다.
위 규칙을 따르며 REST API 설계 중 고민했던 사항들에 관해 정리해보고자 한다.
1. 회원가입과 회원탈퇴 url 엔드포인트 선택
회원가입과 회원탈퇴 api url에 있어 처음 떠올린 바는 각각 POST /users/signup과 DELETE /users/withdrawal이었다. 하지만 명확성을 위해 url엔 접근할 리소스의 경로만 남겨 표현하는 것을 지향해 POST /users와 DELETE /users로 수정하였다.
2. 로그인의 HTTP method는 무엇일까
POST라는 결론을 내렸다. GET 사용 시, 일반적으로 body를 쓰지 않고 필요한 데이터 전달 시 query string과 path variable을 사용한다. 하지만 보안과 관련된 정보인 로그인 입력 정보를 URL에 담아 보내는 것은 위험하다. 이러한 이유로 body를 쓰는 POST로 안전하게 정보를 보내는 게 적합하다고 생각해 POST로 결정했다.
로그인 과정은 session을 만든다는 점에서 POST라는 의견도 보았지만 데이터베이스의 리소스를 생성하는 것은 아니라는 점에서 맞지 않다고 생각했다. token 사용 시 token을 생성한다는 점에서 POST라는 의견도 보았지만 같은 이유로 적절한 근거라고는 생각하지 않았다.
3. 회원가입 시 프로필 이미지 처리
회원 가입에 필요한 필드 입력 후 회원가입을 눌렀는데 이미지 업로드 과정에서 발생한 에러로 회원가입 전체가 실패한다면 유저는 이를 재시도 하지 않고 떠나버릴 수도 있다. 이를 막기 위해 이미지 저장 과정에서 오류가 생기더라도 회원가입은 일단 완료되도록 설계하기로 했다. 회원가입 과정을 하나의 API로 처리하던 것을 JSON으로 값들을 전달받을 API와 이미지 파일을 multipart/form-data로 받아 S3에 올리고 url을 데이터베이스에 저장할 API로, 이렇게 두 개의 API로 분리하는 방법을 채택했다.
게시물 작성, 게시물 수정, 프로필 수정 시에도 같은 방법을 적용해 설계했다.
4. 유효성 검사 관련 응답 status code
결론적으로 명세서에 기재한 부분과의 불일치로 인해 생기는 문제들은 모두 400으로 응답하도록 했다. 명세서에 기재된 부분이라고 하면 필수 필드 누락, 필드 타입 오류, 유효성 검사 조건, 데이터 형식 등이 해당한다.
5. 글 생성 후 응답
글 생성 후 글 상세보기 뷰를 보여주는 것이 일반적이기에 내용, 작성자, 작성일자 등의 데이터 값을 response body에 보내야 하나 고민했지만 글 상세보기 API를 통해 얻도록 하는 게 맞을 것 같아 글 생성 후엔 postid만을 반환하도록 했다.
6. 리소스 삭제 처리
회원 탈퇴, 글 삭제 등 리소스 삭제의 경우 데이터 분석을 목적으로, 자원을 바로 지우지 않고 남겨두는 soft delete 방식으로 구현하기 위해 삭제 여부를 boolean 값으로 저장하는 is_deleted 필드를 사용하기로 했다. 삭제 시 이를 true로 만들어 삭제됐음을 표시하고 자원은 그대로 남겨둔다.
7. 토큰 관련 api 리소스 분리
token 최초 생성, token refresh 등과 같이 token과 관련된 작업들은 엔드포인트를 auth로 두고 회원 정보와 관련된 작업들은 users로 하여 구별되도록 설계했다.