API 명세서 [REST API] Ver.1

프로젝트 설계 초반에  RESTful한 API 와 GraphQL API 중 어떤 방식으로 API를 짤지 고민을 하였다.

 

 

 

REST(Representational State Transfer)의 약자로 자원을 이름으로 구분하여 해당 자원의 상태를 주고받는 모든 것을 나타낸다.

즉 REST란 

HTTP URI(Uniform Resource Identifier)를 통해 자원(Resource)을 명시하고,

HTTP Method(POST, GET, PUT, DELETE, PATCH 등)를 통해

해당 자원(URI)에 대한 CRUD Operation을 적용하는 것을 의미한다.

 

 

GraphQL API는 쿼리 언어를 사용하여 데이터를 조작하는 API이며  단일 URL 엔드포인트를 가지고 있다.

클라이언트는 필요한 데이터를 얻기 위해 GraphQL 쿼리를 사용하여 HTTP 요청을 보낸다.

GraphQL API는 클라이언트가 정의한 유연한 구조로 데이터를 반환한다.

 

결론 적으로는  백엔드와 프론트엔드간의 데이터 통신을 하는 방식은 기본적으로 REST API를 사용할 것이다.

 

그 이유 로는 현재 GraphQL이 페이스북에서 밀어주며 상승세를 보이고 있지만 간단한 쿼리르 작성하며 사용해본 결과

아무래도 쭉 사용하던 REST API가 더 가시적으로나 이해가 편했다.

또한 아직 GraphQL은 표준화가 되지 않았으며 사용자가 적어서 차후 나의 코드를 보러온 많은 사람들의

유입까지 생각해보면 역시 굳이 사용을 하고 싶지가 않았다.

또한 현재 프로젝트에서 처음 개발하는 부분이 많아서 새로운 쿼리 언어를 사용하는 것에 대한 러닝 커브 또한

REST API 를 결정하는데 한몫 하였다.

 

 

 

물론 NestJS로 개발을 할 것이어서 스웨거로  API 명세서를 문서화 할 것이지만 

우선 개발이 들어가기 앞서 전반적인 API 를 짜보았다.

 

 

API 명세서

우선 소켓 통신을 제외한 API 명세서를 작성해 보았다.

모듈별로 큰 틀로 필요 기능만 적은 수준으로 적었고 개발시 하나하나 다시 스웨거로 API 명세서를 문서화할 예정이다.

 

 

 

 

각 백엔드 모듈 단위로 첫 도메인으로 나누었다.

아직 각 게시물이나 댓글 채팅 들의 Idx를 쿼리로 받을지  바디로 받을지 정하지 못하였다.

또한 채팅과 알람의 경우에는 user,post,comment 모듈 작업이 끝나면 전면 수정이 필수이다.

차후 실직적 개발에 들어가면 확실히 정해 보아야 겠다.

 

 

 

 

WebSocket

웹소켓 API

 

socket.on

서버에서 클라이언트로 보내는 이벤트(클라이언트에서는 on으로 받음)

 

hello

소켓 연결 테스트용 API

서버 data: string(네임스페이스 이름)

onlineList

현재 온라인인 사람들 아이디 목록

서버 data: number[](아이디 목록)

message

새로운 채널 메시지가 올 때

서버 데이터: IChat(채팅 데이터)

dm

새로운 dm 메시지가 올 때

서버 데이터: IDM(dm 데이터)

socket.emit

클라이언트에서 서버로 보내는 이벤트(클라이언트에서는 emit으로 보냄)

 

login

워크스페이스, 채널이 로딩 완료되었을 때 서버에 로그인했음을 알리는 이벤트

클라이언트 data: { id: number(유저 아이디), channels: number[](채널 아이디 리스트) }

disconnect

클라이언트에서 소켓 연결을 종료하는 함수