Skip to content

Instantly share code, notes, and snippets.

@therne

therne/README.md

Last active December 30, 2015 22:49
Show Gist options
  • Save therne/7896258 to your computer and use it in GitHub Desktop.
Save therne/7896258 to your computer and use it in GitHub Desktop.
Download ZIP
Clutch API Documentation
Raw
README.md

Clutch Application Server

클러치 서비스의 어플리케이션 서버이다.

서버 언어로는 Node.js를 사용하며, ExpressJs 및 ejs를 사용하여 API와 웹 백엔드를 구축한다. 데이터베이스 엔진으로는 MongoDB, 드라이버로는 mongoose를 사용한다.

클라이언트단에서 서버로의 모든 호출은 비동기식으로 이루어지며(Asynchronize), 서버는 그 요청을 처리해 JSON 형태의 결과값을 HTTP 응답 형태(application/json)로 반환한다.

서버에서 각각의 REST 메서드와 클라이언트의 인터페이스 메서드는 서로 대응된다.

Base Server Information

Main URL : http://dev.thedeblur.com:1129

서비스 오픈 전까지 임시로 Deblur의 개발서버를 사용한다.

REST API BASICS

다음과 같은 명령어들이 존재한다.
GET : 해당 리소스를 가져오거나, 리스팅한다.
POST : 해당 리소스를 생성한다.
PATCH : 해당 리소스를 수정한다.
PATCH : 해당 리소스를 수정한다.
PUT : 해당 리소스에 파일을 업로드한다.

헤더를 사용하는 경우는 접근이 제한된 리소스를 인증할 때(token) 빼고는 없으며, 대부분의 파라미터는 GET에서는 Query(x=1&y=2)로, POST, PATCH, DELETE에서는 FormUrlEncoded로 전달된다.

Response의 타입은 무조건 application/json이며, API 호출 결과인 status라는 항목을 포함한다.

Sample JSON Response
{
    "status" : {
        "code" : "200",
        "message" : "성공"
    },
    "key" : “value",
    "key" : “value”,
    (....)
}
API STATUS CODE
Code Status Message
200 SUCCEED 성공
400 FAILED 실패 (서버 내부 오류)
411 FAILED_LESS_PARAMETER 파라미터 부족
1000 FAILED_DB_CONNECTION 데이터베이스 내부 오류
401 FAILED_NO_PERMISSION 권한 부족
402 FAILED_TOKEN_INVALID Auth 토큰 불일치
1001 FAILED_ACCOUNT_INVALID 계정 불일치
1002 FAILED_ALREADY_EXISTS 아이디가 이미 존재

이 코드들은 클라이언트의 Clutch.Status 클래스와 서버의 status.json에 모두 정의되어 있다.

API OVERVIEW

###METADATA STORE

  • PUT /pictures
  • GET /pictures/full/:metadataId
  • GET /pictures/thumb/:metadataId
  • GET /pictures/custom/:metadataId/:width/:height

###USER

  • POST /user/register
  • POST /user/login
  • GET /user/:id
  • GET /user/:id/picture
  • POST /user/:id/picture
  • GET /user/:id/star
  • POST /user/:id/star
  • GET /user/:id/followers
  • GET /user/:id/followings
  • POST /user/:id/followings
  • DELETE /user/:id/followings
  • PATCH /user/:id
  • PATCH /user/:id/star
  • DELETE /user/:id

###Clutch

  • GET /clutch
  • POST /clutch
  • DELETE /clutch/:id
  • POST /clutch/:id/like
  • GET /clutch/:id/comments
  • POST /clutch/:id/comments
  • DELETE /clutch/:id/comments/:commentId

###Clutch Book

  • GET /user/:id/cb
  • POST /user/:id/cb
  • GET /user/:id/cb/:cbId
  • PUT /user/:id/cb/:cbId
  • DELETE /user/:id/cb/:cbId
  • GET /user/:id/cb/:cbId/followers
  • GET /user/:id/cb/:cbId/followings
  • POST /user/:id/cb/:cbId/followings

###Community

  • GET /community
  • POST /community/:articleId/
  • PUT /community/:articleId/
  • DELETE /community/:articleId/
  • POST /community/:articleId/like
  • GET /community/:articleId/
  • GET /community/:articleId/comments
  • POST /community/:articleId/comments
  • DELETE /community/:articleId/comments/:commentId

###Artist

  • GET /artist/:artistId/

###Notification

  • GET /notifications/me
  • GET /notifications/friends

###Ranking

  • GET /ranking/
  • GET /ranking/:date/details

###Settings

  • GET /user/:id/settings/:key
  • POST /user/:id/settings/:key

2. User

NOTE

유저의 개인적인 정보에 접근하고 수정하기 위해선 인증이 필요한데, 이때 토큰이 필요하다.
유저의 공개적인 정보(프로필)에 접근하기 위해서는 유저의 고유번호인 User ID를 알아야 한다.
토큰은 HTTP Request의 Header에 token이란 필드에 들어가며, userId는 URL 자체에 경로로 들어간다.
그러므로 토큰과 유저ID는 로그아웃 전까지 클라이언트의 저장소에 임시로 저장해야 한다.

========

POST /user/register - 회원가입

유저가 Clutch 서비스에 회원가입할 때 사용됩니다.
picture 필드를 채울땐 먼저 메타데이터 스토어에 이미지를 업로드 한 뒤 Metadata ID를 주면 됩니다.

REQUEST
Name Type Description
email String 이메일 주소
pw String 패스워드 (MD5 해싱 필수!)
name String 유저 프로필의 상태 메세지
status_message String 유저 프로필의 상태 메세지
picture String 유저의 프로필 사진 (Metadata ID)
gender Number 성별 (남자=0, 여자=1)
RESPONSE
Name Description
userToken 유저의 토큰. 개인정보 접근시 인증에 사용된다.
userId 유저의 고유번호. 공개적인 정보 접근에 사용됨.
STATUS
Code Status Message
200 SUCCESS 성공
1002 REGISTER_ACOUNT_EXISTS 이메일 중복
SAMPLE DATA


POST /user/register
email=test@clutch.com
pw=5d41402abc4b2a76b9719d911017c592   // MD5("hello")
status_message=Hello
picture=(none)
gender=0

>>>>>>>>>>
{
status: { code: 200, message: "성공" },
userId: (User ID),
userToken: (user Token)
}





========


POST /user/login - 로그인


유저가 Clutch 서비스에 로그인할 때 사용됩니다.


REQUEST






Name
Type
Description






email
String
이메일 주소




pw
String
패스워드 (MD5 해싱 필수!)






RESPONSE






Name
Description






userToken
유저의 토큰. 개인정보 접근시 인증에 사용된다.




userId
유저의 고유번호. 공개적인 정보 접근에 사용됨.






STATUS






Code
Status
Message






200
SUCCESS
성공




1001
LOGIN_FAILED_ACCOUNT_MISMATCH
계정 불일치






SAMPLE DATA






POST /user/login
email=test@clutch.com
pw=5d41402abc4b2a76b9719d911017c592   // MD5("hello")
>>>>>>>>>>
{
status: { code: 200, message: "성공" },
userId: (User ID),
userToken: (user Token)
}





========


GET /user/:id - 프로필 얻기


한 유저의 프로필을 얻어올 때 사용된다. 


REQUEST






Name
Type
Description






id
String
원하는 유저의 ID






RESPONSE






Name
Description






profile
유저의 프로필 (JSON 객체)




profile.name
이름




profile.status_message
유저 프로필의 상태 메세지




profile.picture
유저의 프로필 사진 (Metadata ID)




profile.followers_count
팔로워들의 수




profile.followings_count
팔로잉하는 수




profile.gender
성별 (남자=0, 여자=1)




profile.last_photos
유저의 대표 사진 5개 (Metadata ID)






SAMPLE DATA






GET /user/52ff32f5ce6c300f55000003
>>>>>>>>>>
{
status: { code: 200, message: "성공" },
profile: {
name: "김료준",
status_message: "안뇽안뇽~",
picture: "(no pic)",
followers_count: 3,
followings_count: 0,
gender: 0,
last_photos: []
}
}





========


GET /user/:id/picture - 프로필 사진 얻기


한 유저의 프로필 사진을 얻어올 때 사용된다. 


REQUEST






Name
Type
Description






id
String
원하는 유저의 ID




x
Number
(옵션) 원하는 사진의 가로크기




y
Number
(옵션) 원하는 사진의 세로크기






RESPONSE


Content-Type: image/jpeg

Body: (프로필 사진)


SAMPLE DATA






GET /user/52ff32f5ce6c300f55000003/picture?x=300&y=300
>>>>>>>>>>
Content-Type: image/jpeg
Body: (프로필 사진)





========


PUT /user/:id/picture - 프로필 사진 업로드


한 유저의 프로필 사진을 바꿀 때 사용된다. 


HEADER






Name
Description






token
유저의 토큰






REQUEST






Name
Type
Description






id
String
원하는 유저의 ID




picture
(multipart) File
프로필 이미지 파일






RESPONSE


SAMPLE DATA






PUT /user/52ff32f5ce6c300f55000003/picture
>>>>>>>>>>
{ status: { code: 200, message: "성공" }}





========


GET /user/:id/star - 유저의 풍선 갯수 보기


REQUEST






Name
Type
Description






id
String
원하는 유저의 ID






RESPONSE






Name
Description






star
풍선 갯수






SAMPLE DATA






GET /user/52ff32f5ce6c300f55000003/star
>>>>>>>>>>
{
status: { code: 200, message: "성공" },
stars: 0
}





========


POST /user/:id/star - 유저에게 풍선 추가


HEADER






Name
Description






token
유저의 토큰






REQUEST






Name
Type
Description






id
String
원하는 유저의 ID




count
Number
주기를 원하는 풍선 갯수






SAMPLE DATA






POST /user/52ff32f5ce6c300f55000003/star
>>>>>>>>>>
{ status: { code: 200, message: "성공" } }





========


GET /user/:id/followers - 팔로어 목록 구하기


유저의 팔로어 목록을 구한다. 리스트 형식으로 Response한다.


REQUEST






Name
Type
Description






id
String
원하는 유저의 ID




pageNo
Number
몇번째 페이지의 결과를 원하는가




pageCount
Number
한페이지에 몇개의 결과를 넣는가






RESPONSE






Name
Description






followers
팔로어 배열




followers.id
팔로어 ID




followers.name
팔로어 이름




followers.status_message
팔로어 상태 메세지




followers.picture
팔로어 프로필 사진 ID




followers.followers_count
팔로어의 팔로어 명수




followers.followings_count
팔로어의 팔로잉 명수




followers.gender
팔로어의 팔로잉 명수




followers.last_photos[]
팔로어의 대표 사진 5장






SAMPLE DATA






GET /user/52ff32f5ce6c300f55000003/followers?pageNo=0&pageCount=50
>>>>>>>>>>
{
status: { code: 200, message: "성공" },
followers: [
{
id: 52ff32f5ce6c300f55000014,
name: "김유저",
status_message: "유저1입니다. 안뇽~",
picture: (no pic),
followers_count: 0,
followings_count: 1,
gender: 1,
last_photos: [a,b,c,d,e]
},
{
id: 6a6831f4ce6c300f55000025,
name: "박유저",
status_message: "유저2입니다. 안뇽~",
picture: (no pic),
followers_count: 51,
followings_count: 1,
gender: 0,
last_photos: [b,C,a,D,x]
}
]
}





========


GET /user/:id/followings - 팔로잉 목록 구하기


REQUEST






Name
Type
Description






id
String
원하는 유저의 ID




pageNo
Number
몇번째 페이지의 결과를 원하는가




pageCount
Number
한페이지에 몇개의 결과를 넣는가






RESPONSE






Name
Description






followings
팔로잉 배열




followings.id
팔로잉의 ID




followings.name
팔로잉 이름




followings.status_message
팔로잉의 상태 메세지




followings.picture
팔로잉의 프로필 사진 ID




followings.followers_count
팔로잉의 팔로어 명수




followings.followings_count
팔로잉의 팔로잉 명수




followings.gender
팔로잉의 팔로잉 명수




followings.last_photos[]
팔로잉의 대표 사진 5장






SAMPLE DATA






GET /user/52ff32f5ce6c300f55000003/followings?pageNo=0&pageCount=50
>>>>>>>>>>
{
status: { code: 200, message: "성공" },
followings: [
{
id: 52ff32f5ce6c300f55000014,
name: "김유저",
status_message: "유저1입니다. 안뇽~",
picture: (no pic),
followers_count: 0,
followings_count: 1,
gender: 1,
last_photos: [a,b,c,d,e]
},
{
id: 6a6831f4ce6c300f55000025,
name: "박유저",
status_message: "유저2입니다. 안뇽~",
picture: (no pic),
followers_count: 51,
followings_count: 1,
gender: 0,
last_photos: [b,C,a,D,x]
}
]
}





========


POST /user/:id/followings - 팔로잉하기


HEADER






Name
Description






token
유저의 토큰






REQUEST






Name
Type
Description






id
String
유저의 ID




following_id
String
팔로우를 원하는 유저의 ID






SAMPLE DATA






POST /user/52ff32f5ce6c300f55000003/followings
>>>>>>>>>>
{ status: { code: 200, message: "성공" } }





========


DELETE /user/:id/followings - 팔로잉 해제


HEADER






Name
Description






token
유저의 토큰






REQUEST






Name
Type
Description






id
String
유저의 ID




following_id
String
팔로우 해제를 원하는 유저의 ID






SAMPLE DATA






DELETE /user/52ff32f5ce6c300f55000003/followings
>>>>>>>>>>
{ status: { code: 200, message: "성공" } }





========


PATCH /user/:id - 프로필 수정


HEADER






Name
Description






token
유저의 토큰






REQUEST






Name
Description






id
유저의 ID




name
이름




status_message
유저 프로필의 상태 메세지




picture
유저의 프로필 사진 (Metadata ID)




gender
성별 (남자=0, 여자=1)




pw
패스워드 (MD5 해싱 필수!)






SAMPLE DATA






PATCH /user/52ff32f5ce6c300f55000003
name="김료준"
status_message="수정된 상태 메세지!"
pw='24b7059cb0f4df701401ddf854d770ee'  // MD5("Halloo")
>>>>>>>>>>
{ status: { code: 200, message: "성공" } }





========


DELETE /user/:id - 회원 탈퇴


회원을 탈퇴하고 DB에서 모든 데이터를 지웁니다.


HEADER






Name
Description






token
유저의 토큰






SAMPLE DATA






DELETE /user/52ff32f5ce6c300f55000003/followings
>>>>>>>>>>
{ status: { code: 200, message: "성공" } }





2. Clutch


NOTE


모든 클러치는 클러치북에 존속된다. 그렇다고 클러치의 리소스는 클러치북 안에 속해있지 않으며 독자적이다. (/clutch) 또한, 자신이 클러치를 올리고 좋아요를 누르는 등의 기타 행동들은 모두 자신의 팔로워들에게 알림이 전달된다. **또한 클러치와 관련된 모든 활동들은 Header의 token을 통한 유저 인증이 필요하지만 문서에는 전부 중복 기재하지 않겠다. 이것은 기본 요구사항이다. **





POST /clutch - 새로운 클러치 쓰기


REQUEST






Name
Description






tags
클러치에 들어가는 태그들 (쉼표로 구분)




cb_id
이 클러치가 속하는 클러치북 ID




content_type
사진: 0, 동영상: 1, 링크: 2




content_pictures
(사진일 경우) 사진의 메타데이터 ID들 (공백으로 구분)




content_link
(동영상/링크일 경우) 해당하는 URL




content_body
글 내용






RESPONSE






Name
Description






clutchId
이 클러치의 ID






SAMPLE DATA






POST /clutch
cb_id="30501304"
tags="존예,여신,걸스데이""
content_type=0
content_pictures="pic1id pic2id pic3id"
content_body="민아 존예..."
>>>>>>>>>>
{
status: { code: 200, message: "성공" },
clutchId: fa4230491alf
}





========


GET /clutch - 클러치 가져오기 (타임라인!)


REQUEST






Name
Description






sort
정렬. (0: 인기순, 1: 최신순)




pageNo
요청하는 페이지 번호




pageCount
한 페이지당 로딩할 클러치 갯수






RESPONSE






Name
Description






clutches
로딩된 클러치 목록(리스트)




clutches.clutchId
이 클러치의 ID




clutches.cb_id
클러치북의 ID




clutches.cb_name
클러치북 이름




clutches.userId
클러치를 올린 유저의 ID




clutches.userName
클러치를 올린 유저의 이름




clutches.userPhoto
클러치를 올린 유저의 프로필 사진




clutches.content_type
클러치 종류




clutches.content_pictures
(옵션, 사진만) 사진들 (공백으로 구분)




clutches.content_link
(옵션, 동영상 및 링크만) 링크 URL




clutches.content_link_thumb
(옵션, 동영상 및 링크만) 링크 썸네일 이미지






SAMPLE DATA






GET /clutch
sort=0
pageNo=0
pageCount=50
>>>>>>>>>>
{
status: { code: 200, message: "성공" },
clutches: [
{
clutchId: "fa4230491alf",
cb_id: "fa4230491alf",
cb_name: "걸스데이",
userId: "fa4230491alf",
userName: "신광수",
userPhoto: "(no pic)",
content_type: 0,
content_pictures: "pic1id pic2id"
},
{
clutchId: "fa4230491alf",
cb_id: "fa4230491alf",
cb_name: "소녀시대",
userId: "fa4230491alf",
userName: "이호연"
userPhoto: "(no pic)",
content_type: 1,
content_link: "http://thedeblur.com:1129/videos/1934205"
content_link_thumb: "(no pic)"
}
]
}





========


DELETE /clutch/:clutchId - 클러치를 지운다.


REQUEST






Name
Description






clutchId
지우고 싶은 클러치의 ID






RESPONSE


SAMPLE DATA






DELETE /clutch/fa4230491alf
>>>>>>>>>>
{ status: { code: 200, message: "성공" } }





========


POST /clutch/:clutchId/like - 좋아요를 누른다.


REQUEST






Name
Description






clutchId
좋아하는 클러치의 ID






RESPONSE


SAMPLE DATA






POST /clutch/fa4230491alf/like
>>>>>>>>>>
{ status: { code: 200, message: "성공" } }





========


DELETE /clutch/:clutchId/like - 좋아요를 해제한다.


REQUEST






Name
Description






clutchId
좋아요를 해제할 클러치의 ID






RESPONSE


SAMPLE DATA






DELETE /clutch/fa4230491alf/unlike
>>>>>>>>>>
{ status: { code: 200, message: "성공" } }





========


GET /clutch/:clutchId/comments - 댓글을 가져온다.


REQUEST






Name
Description






clutchId
댓글을 가져올 클러치의 ID




pageNo
요청하는 페이지 번호




pageCount
한 페이지당 로딩할 댓글 갯수






RESPONSE






Name
Description






comments
로딩된 댓글 목록




comments.commentId
이 클러치의 ID




comments.userId
댓글을 쓴 유저의 ID




comments.userName
댓글을 쓴 유저의 이름




comments.userPhoto
댓글을 쓴 유저의 프로필 사진




comments.body
댓글 내용




comments.date
댓글을 쓴 시간 (Timestamp)




comments.likeCount
댓글이 받은 추천 갯수




comments.unlikeCount
댓글이 받은 비추천 갯수






SAMPLE DATA






GET /clutch/fa4230491alf/comments
pageNo=0
pageCount=50
>>>>>>>>>>
{
status: { code: 200, message: "성공" },
comments: [
{
commentId: "fa4230491alf",
userId: "fa4230491alf"
userName: "김효준",
userPhoto: "(no pic)",
body: "와... 정말 예쁘네요",
likeCount: 0,
unlikeCount: 0,
date: 1292667739248
},
{
commentId: "fa4230491alf",
userId: "fa4230491alf",
userName: "홍길동",
userPhoto: "(no pic)",
body: "진심 너무 예쁘네요",
likeCount: 1,
unlikeCount: 0,
date: 1392667736248
}]
}





========


DELETE /clutch/:clutchId/comments/:commentId - 댓글을 삭제한다.


REQUEST






Name
Description






clutchId
댓글 삭제의 대상이 되는 클러치의 ID




commentId
삭제할 댓글의 ID






RESPONSE


SAMPLE DATA






DELETE /clutch/fa4230491alf/comments/104059/delete
>>>>>>>>>>
{ status: { code: 200, message: "성공" } }





========


POST /clutch/:clutchId/comments/:commentId/like - 댓글을 추천한다.


DELETE 명령어를 통해 추천을 해제할 수 있다.


REQUEST






Name
Description






clutchId
댓글 추천의 대상이 되는 클러치의 ID




commentId
추천할 댓글의 ID






RESPONSE


STATUS CODE






Code
Status
Message






2002
ALREADY_UNLIKED
이미 비추천을 누른 상태임






SAMPLE DATA






POST /clutch/fa4230491alf/comments/104059/like
>>>>>>>>>>
{ status: { code: 2002, message: "이미 비추천을 누르셨습니다." } }





========


POST /clutch/:clutchId/comments/:commentId/unlike - 댓글을 비추천한다.


DELETE 명령어를 통해 비추천을 해제할 수 있다.


REQUEST






Name
Description






clutchId
댓글 추천의 대상이 되는 클러치의 ID




commentId
추천할 댓글의 ID






RESPONSE


STATUS CODE






Code
Status
Message






2001
ALREADY_LIKED
이미 추천을 누른 상태임






SAMPLE DATA






POST /clutch/fa4230491alf/comments/104059/like
>>>>>>>>>>
{ status: { code: 2001, message: "이미 추천을 누르셨습니다." } }







3. Clutch Book


NOTE


모든 클러치는 클러치북에 존속된다. 클러치북의 리소스는 유저 안에 속해있다. (/user/:userId/cb)

또한, 클러치북을 지칭할때는 clutchbook이 아닌 cb로 지칭한다.





POST /user/:userId/cb - 새로운 클러치북 생성


REQUEST






Name
Description






name
클러치북 이름




desc
클러치북 설명




coverPics
클러치북 커버들




tags
들어가는 태그들 (쉼표로 구분)






RESPONSE






Name
Description






cb_id
이 클러치북의 ID






SAMPLE DATA






POST /user/fa4230491alf/cb
name="걸스데이"
desc="걸스데이 사진 저장하는 곳!"
tags="존예,여신,걸스데이""
>>>>>>>>>>
{
status: { code: 200, message: "성공" },
cb_id: fa4230491alf
}





========


DELETE /user/:userId/cb/:cb_id - 클러치북 삭제


REQUEST






Name
Description






cb_id
지우려는 클러치북 ID






SAMPLE DATA






DELETE /user/fa4230491alf/cb/aa31347f
>>>>>>>>>>
{ status: { code: 200, message: "성공" } }





========


GET /user/:userId/cb/:cb_id - 클러치북 안에 있는 클러치 목록


REQUEST






Name
Description






cb_id
요청하는 클러치북 ID




sort
정렬 (0: 인기순, 1: 최신순)




pageNo
요청하는 페이지 번호




pageCount
한 페이지당 로딩할 댓글 갯수






RESPONSE






Name
Description






clutches
로딩된 클러치 목록(리스트)




clutches.clutchId
이 클러치의 ID




clutches.cb_id
클러치북의 ID




clutches.cb_name
클러치북 이름




clutches.userId
클러치를 올린 유저의 ID




clutches.userName
클러치를 올린 유저의 이름




clutches.userPhoto
클러치를 올린 유저의 프로필 사진




clutches.content_type
클러치 종류




clutches.content_pictures
(옵션, 사진만) 사진들 (공백으로 구분)




clutches.content_link
(옵션, 동영상 및 링크만) 링크 URL




clutches.content_link_thumb
(옵션, 동영상 및 링크만) 링크 썸네일 이미지






SAMPLE DATA






GET /user/fa4230491alf/cb/1853ffba
sort=0
pageNo=0
pageCount=50
>>>>>>>>>>
{
status: { code: 200, message: "성공" },
clutches: [
{
clutchId: "fa4230491alf",
cb_id: "fa4230491alf",
cb_name: "걸스데이",
userId: "fa4230491alf",
userName: "신광수",
userPhoto: "(no pic)",
content_type: 0,
content_pictures: "pic1id pic2id"
},
{
clutchId: "fa4230491alf",
cb_id: "fa4230491alf",
cb_name: "걸스데이",
userId: "fa4230491alf",
userName: "이호연"
userPhoto: "(no pic)",
content_type: 1,
content_link: "http://thedeblur.com:1129/videos/1934205"
content_link_thumb: "(no pic)"
}
]
}





========



  


  





      
      

        

          

            









          


          

            

  
    Sign up for free
    to join this conversation on GitHub.
    Already have an account?
    Sign in to comment