Skip to content

API documentation

Jump to bottom
Hoony edited this page Aug 30, 2021 · 8 revisions

현 스터디는 real world 오픈소스에서 제공하는 표준 API 스펙을 따라갑니다.

모든 api는 JSON 객체로써 반환되어야 합니다.

Content-Type: application/json; charset=utf-8

End Point

User

Authentication

POST /api/users/login

No authentication

최초 로그인시 아이디와 비밀번호를 통해 인증을 받는다.

Example request body:

Requried fields: email, password

{
  "user":{
    "email": "[email protected]",
    "password": "jakejake"
  }
}

Response:

{
  "user": {
    "email": "[email protected]",
    "token": "jwt.token.here",
    "username": "jake",
    "bio": "I work at statefarm",
    "image": null
  }
}

Registration

POST /api/users

No authentication

회원 가입 시 유저의 정보를 입력하고 회원가입한다.

Example request body:

Required fields: email, username, password

{
  "user":{
    "username": "Jacob",
    "email": "[email protected]",
    "password": "jakejake"
  }
}

Response:

{
  "user": {
    "email": "[email protected]",
    "token": "jwt.token.here",
    "username": "jake",
    "bio": "I work at statefarm",
    "image": null
  }
}

Get Current User

GET /api/user

Authentication

현재 로그인된 유저의 정보를 반환한다.

Response:

{
  "user": {
    "email": "[email protected]",
    "token": "jwt.token.here",
    "username": "jake",
    "bio": "I work at statefarm",
    "image": null
  }
}

Update User

PUT /api/user

Authentication

현재 로그인된 유저의 정보를 업데이트한다.

Request body:

Accepted fields: email, username, password, image, bio

{
  "user":{
    "email": "[email protected]",
    "bio": "I like to skateboard",
    "image": "https://i.stack.imgur.com/xHWG8.jpg"
  }
}

Response:

{
  "user": {
    "email": "[email protected]",
    "token": "jwt.token.here",
    "username": "jake",
    "bio": "I work at statefarm",
    "image": null
  }
}

Get Profile

GET /api/profiles/{username}

Autentication optional

해당 유저의 프로필 정보를 반환한다.

Response:

{
  "profile": {
    "username": "jake",
    "bio": "I work at statefarm",
    "image": "https://static.productionready.io/images/smiley-cyrus.jpg",
    "following": false
  }
}

Follow

Follow User

POST /api/profiles/{username}/follow

Authentication

해당 유저를 팔로우한다.

Response:

{
  "profile": {
    "username": "jake",
    "bio": "I work at statefarm",
    "image": "https://static.productionready.io/images/smiley-cyrus.jpg",
    "following": false
  }
}

Unfollow User

DELETE /api/profiles/{username}/follow

Authentication

해당 유저를 언팔로우한다.

Response:

{
  "profile": {
    "username": "jake",
    "bio": "I work at statefarm",
    "image": "https://static.productionready.io/images/smiley-cyrus.jpg",
    "following": false
  }
}

Article

List Articles

GET /api/articles

Authentication optional

가장 최근에 작성된 게시글부터 반환해야 한다.

tag, author, favorited 쿼리 파라미터로 필터링하여 제공할 수 있다.

Accepted query parameter

Filtering by tag, author, favorited: ?tag=AngularJS ,?author=jake, ?favorited=jake

Limit number of articles (default is 20): ?limit=20

Offset / Skip number of articles (default is 0): ?offset=0

Response:

{
  "articles":[{
    "slug": "how-to-train-your-dragon",
    "title": "How to train your dragon",
    "description": "Ever wonder how?",
    "body": "It takes a Jacobian",
    "tagList": ["dragons", "training"],
    "createdAt": "2016-02-18T03:22:56.637Z",
    "updatedAt": "2016-02-18T03:48:35.824Z",
    "favorited": false,
    "favoritesCount": 0,
    "author": {
      "username": "jake",
      "bio": "I work at statefarm",
      "image": "https://i.stack.imgur.com/xHWG8.jpg",
      "following": false
    }
  }, {
    "slug": "how-to-train-your-dragon-2",
    "title": "How to train your dragon 2",
    "description": "So toothless",
    "body": "It a dragon",
    "tagList": ["dragons", "training"],
    "createdAt": "2016-02-18T03:22:56.637Z",
    "updatedAt": "2016-02-18T03:48:35.824Z",
    "favorited": false,
    "favoritesCount": 0,
    "author": {
      "username": "jake",
      "bio": "I work at statefarm",
      "image": "https://i.stack.imgur.com/xHWG8.jpg",
      "following": false
    }
  }],
  "articlesCount": 2
}

Feed Articles

GET /api/articles/feed

authentication

GET /api/articles과 동일하게 limit과 offset을 설정할 수 있다.

Response:

{
  "articles":[{
    "slug": "how-to-train-your-dragon",
    "title": "How to train your dragon",
    "description": "Ever wonder how?",
    "body": "It takes a Jacobian",
    "tagList": ["dragons", "training"],
    "createdAt": "2016-02-18T03:22:56.637Z",
    "updatedAt": "2016-02-18T03:48:35.824Z",
    "favorited": false,
    "favoritesCount": 0,
    "author": {
      "username": "jake",
      "bio": "I work at statefarm",
      "image": "https://i.stack.imgur.com/xHWG8.jpg",
      "following": false
    }
  }, {
    "slug": "how-to-train-your-dragon-2",
    "title": "How to train your dragon 2",
    "description": "So toothless",
    "body": "It a dragon",
    "tagList": ["dragons", "training"],
    "createdAt": "2016-02-18T03:22:56.637Z",
    "updatedAt": "2016-02-18T03:48:35.824Z",
    "favorited": false,
    "favoritesCount": 0,
    "author": {
      "username": "jake",
      "bio": "I work at statefarm",
      "image": "https://i.stack.imgur.com/xHWG8.jpg",
      "following": false
    }
  }],
  "articlesCount": 2
}

by followed users

Get Article

GET /api/articles/{slug}

No authentication

slug로 들어온 특정 게시글을 조회한다.

Response:

{
  "article": {
    "slug": "how-to-train-your-dragon",
    "title": "How to train your dragon",
    "description": "Ever wonder how?",
    "body": "It takes a Jacobian",
    "tagList": ["dragons", "training"],
    "createdAt": "2016-02-18T03:22:56.637Z",
    "updatedAt": "2016-02-18T03:48:35.824Z",
    "favorited": false,
    "favoritesCount": 0,
    "author": {
      "username": "jake",
      "bio": "I work at statefarm",
      "image": "https://i.stack.imgur.com/xHWG8.jpg",
      "following": false
    }
  }
}

Create Article

POST /api/articles

authentication

게시글을 추가한다.

Example request body:

Required fields: title, description, body

Optional fields: tagList as an array of Strings

{
  "article": {
    "title": "How to train your dragon",
    "description": "Ever wonder how?",
    "body": "You have to believe",
    "tagList": ["reactjs", "angularjs", "dragons"]
  }
}

Response:

{
  "article": {
    "slug": "how-to-train-your-dragon",
    "title": "How to train your dragon",
    "description": "Ever wonder how?",
    "body": "It takes a Jacobian",
    "tagList": ["dragons", "training"],
    "createdAt": "2016-02-18T03:22:56.637Z",
    "updatedAt": "2016-02-18T03:48:35.824Z",
    "favorited": false,
    "favoritesCount": 0,
    "author": {
      "username": "jake",
      "bio": "I work at statefarm",
      "image": "https://i.stack.imgur.com/xHWG8.jpg",
      "following": false
    }
  }
}

Update Article

PUT /api/articles/{slug}

authentication

게시글을 수정한다.

Example request body:

Optional fields: title, description, body

{
  "article": {
    "title": "Did you train your dragon?"
  }
}

Response:

{
  "article": {
    "slug": "how-to-train-your-dragon",
    "title": "How to train your dragon",
    "description": "Ever wonder how?",
    "body": "It takes a Jacobian",
    "tagList": ["dragons", "training"],
    "createdAt": "2016-02-18T03:22:56.637Z",
    "updatedAt": "2016-02-18T03:48:35.824Z",
    "favorited": false,
    "favoritesCount": 0,
    "author": {
      "username": "jake",
      "bio": "I work at statefarm",
      "image": "https://i.stack.imgur.com/xHWG8.jpg",
      "following": false
    }
  }
}

title이 변경되면 slug도 함께 변경된다.

Delete Article

DELETE /api/articles/{slug}

authentication

게시글을 삭제한다.

Comment

Add Comments to an Article

POST /api/articles/{slug}/comments

authentication

게시글 댓글을 추가한다.

Example request body:

Required fields: body

{
  "comment": {
    "body": "His name was my name too."
  }
}

Response:

{
  "comment": {
    "id": 1,
    "createdAt": "2016-02-18T03:22:56.637Z",
    "updatedAt": "2016-02-18T03:22:56.637Z",
    "body": "It takes a Jacobian",
    "author": {
      "username": "jake",
      "bio": "I work at statefarm",
      "image": "https://i.stack.imgur.com/xHWG8.jpg",
      "following": false
    }
  }
}

Get Comments from an Article

GET /api/articles/{slug}/comments

Authentication optional

slug로 들어온 게시글의 모든 댓글을 조회한다.

Response:

{
  "comments": [{
    "id": 1,
    "createdAt": "2016-02-18T03:22:56.637Z",
    "updatedAt": "2016-02-18T03:22:56.637Z",
    "body": "It takes a Jacobian",
    "author": {
      "username": "jake",
      "bio": "I work at statefarm",
      "image": "https://i.stack.imgur.com/xHWG8.jpg",
      "following": false
    }
  }]
}

Delete Comment

DELETE /api/aticles/{slug}/comments/{id}

Authentication

slug로 들어온 게시글의 id 댓글을 삭제한다.

Favorite

Favorite Article

POST /api/articles/{slug}/favorite

Autentication

게시글 좋아요를 누른다.

Response:

{
  "article": {
    "slug": "how-to-train-your-dragon",
    "title": "How to train your dragon",
    "description": "Ever wonder how?",
    "body": "It takes a Jacobian",
    "tagList": ["dragons", "training"],
    "createdAt": "2016-02-18T03:22:56.637Z",
    "updatedAt": "2016-02-18T03:48:35.824Z",
    "favorited": false,
    "favoritesCount": 0,
    "author": {
      "username": "jake",
      "bio": "I work at statefarm",
      "image": "https://i.stack.imgur.com/xHWG8.jpg",
      "following": false
    }
  }
}

Unfavorite Article

DELETE /api/articles/{slug}/favorite

Àuthentication

Response:

{
  "article": {
    "slug": "how-to-train-your-dragon",
    "title": "How to train your dragon",
    "description": "Ever wonder how?",
    "body": "It takes a Jacobian",
    "tagList": ["dragons", "training"],
    "createdAt": "2016-02-18T03:22:56.637Z",
    "updatedAt": "2016-02-18T03:48:35.824Z",
    "favorited": false,
    "favoritesCount": 0,
    "author": {
      "username": "jake",
      "bio": "I work at statefarm",
      "image": "https://i.stack.imgur.com/xHWG8.jpg",
      "following": false
    }
  }
}

Tag

Get Tags

GET /api/tags

No authentication

Response:

{
  "tags": [
    "reactjs",
    "angularjs"
  ]
}

Errors and Status Codes

요청에 대한 validation 실패하면 422 및 다음 형식의 오류코드가 발생한다다.

{
  "errors":{
    "body": [
      "can't be empty"
    ]
  }
}

Other status codes:

401 : 요청에 인증이 필요하지만 인증되지 않은 경우

403 : 요청에 인가가 필요하지만 사용자에게 수행 권한이 없는 경우

404 : 요청을 수행하기 위한 리소스를 찾을 수 없는 경우

Clone this wiki locally