[노동요 프로젝트 - API 명세서] Restful하게 API 설계하기

노동요 프로젝트를 설계하면서 API 명세서 쓰는 법을 배웠다. 

프론트와 함께 작업하고, 작업기간도 5주 이내로 짧기 때문에, API 를 잘 설계하는 게 중요한 것 같다. 

헷갈렸던 점들을 정리해둔다. 왜인지 노션의 템플릿을 복사해올 수가 없어서, 캡쳐해서 가져왔다. 

 

 

변경: /users/login ->  /users/me

이유: 나의 리소스를 가져온다는 점을 명시하기 위해서 users/me 로 수정했다 

변경2: 원래는 accessToken을 포함했었다. 그러나 accessToken은 로컬스토리지에 저장되기 때문에, response body에 들어갈 필요가 없다 accessToken이 유효하면 유저 정보를 갖고 올 수 있다. 유저 정보 중 userId, username, nickname은 스토리지에 저장되는 부분이다.

 

 

변경 queryString 추가  

이유: 해당 페이지는 List 응답이기 때문에 페이징 처리가 필요하다. page 와 size 파라미터를 추가한다. 

기존: ReponseBody -> user 정보 삭제 

이유: 프론트엔드에서 로그인 시 User 정보를 가져오고 Stateful 하게 저장한다. 매 응답마다 가져올 필요가 없다. 

 

*JPA 페이지 네이션 양식 참고: Spring Boot JPA Step-12 - 페이징 API 만들기 | Popit

 

특정 글 상세 조회 

변경: creator를 따로 만들었었음. creator를 따로 보지 않고 유저 객체를 가져온다. 

이유: creator 가 곧 user 이기도 하고, 프로필 이미지를 가져오려면, 해당 정보를 포함한 유저 객체 가져오는 것이 효율적. 

변경2: request body의 post_id를 삭제

이유: url Endpoint에서 post_id 로 넘기기 때문에, request body에서  굳이 중복으로 넘길 필요가 없다.

 

 

글 수정 기능 

 

변경: videoId 추가 

수정: videoId도 수정 가능하기 때문에 RequestBody에 추가했다. 

 

*Put -> Patch: 좋아요, 신고, 수정 등 기존정보를 두고 일부정보만 업데이트 하는 기능은 Put이 아닌 Patch다. 예를 들어, video Id만 수정하는 값을 보냈는데, put method일 때는 나머지 값이 null로 저장한다. 

 

변경: 회원 가입 APi 추가 

Method: Post

EndPoint: /users

 

이유: 우리 팀은 처음에는 이 api 를 포함하지 않았다(OAuth가 있으니 따로 정보 저장할 필요 없겠지 하고 생각했다) 그런데, 회원가입은 google Oauth 로 하더라도, post 가 되어야 한다 유저 정보를 우리가 갖고 있어야 하는데, 이는 우리가 유저수를 파악하고, 유저가 쓴 글을 트랙킹하는 등 table에 정보를 갖고있어야 하기 때문이다. 

 

글 조회 기능

변경: 기존에는 검색 기능의 api 를 따로 뒀었다. 위의 api 로 통합했다. 

이유: 사실 즉 전체 글 조회, 검색 조회의 api 가 같다. 전체 글에서 조회할 떄는, 따로 url 받아올 필요 없이 querystring에 넣어 주면 된다

 

Jsonproperty는 Camelcase로 (userId, userName 등의 소의 Key값이다)

Url은 케밥케이스로 표시한다(언더바를 쓰면 주소창에서 가독성이 떨어진다.