BoardPick::RESTful API 설계

안준성·2024년 4월 24일
restful api

Project::BoardPick

목록 보기
7/11

기획이 거의 다 나와서 API 설계를 해보려 한다.

24.05.18 API 2차 수정

공통 사항

  • 요청헤더에 사용자의 인증정보가 포함될 수 있다.
  • response에 상태코드가 포함된다.
  • 잘못된 요청에 대한 상태코드와 에러 메시지를 반환할 수 있다.

Base URI

https://boardpick-server.store

보드게임 이름 검색

  • description: 사용자가 입력한 검색어가 이름에 포함된 보드게임을 검색한다.
    정렬에 대한 파라미터도 선택적으로 요청할 수 있다. (미완)
    인증된 사용자의 경우 요청 헤더에 JWT 토큰을 포함해야 한다. (보류)
  • ex
    	GET /api/boardgames/search?query=Catan HTTP/1.1
	Host: example.com
	Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5c...
  • Method: GET
  • URI: /api/boardgames/search
  • parameter:
    - keyword (string, 필수): 사용자가 입력한 검색어
    • page (int): 페이지 번호. 기본값은 0
    • size (int): 페이지 크기. 기본값은 10
  • 요청 예시: /api/boardgames/search?keyword=셀레스티아
    /api/board/games/search?keyword=셀레스티아&page=1&size=5
  • Response:
[
  {
    "id": 1,
    "thumbnailUrl": "https://cf.geekdo-images.com/8kl6m6m_unthBPw9SxoDQQ__thumb/img/vK6rBE3ZjolzG6jEVxJj49MBIc4=/fit-in/200x150/filters:strip_icc()/pic6973677.png",
    "imageUrl": "https://cf.geekdo-images.com/8kl6m6m_unthBPw9SxoDQQ__original/img/FtecAcFxPelZCfbWhZlo85uF2Rg=/0x0/filters:format(png)/pic6973677.png",
    "name": "셀레스티아1",
    "description": "예시용 설명",
    "rating": 0,
    "ratingCount": 0,
    "minPlayers": 2,
    "maxPlayers": 6,
    "playtime": 30,
    "ageLimit": 8,
    "difficulty": 3,
    "rule": "gg",
    "extraVideo": "temp",
    "likes": 1,
    "picked": false,
    "boardGameCategories": [
      {
        "id": 1
      },
      {
        "id": 2
      }
    ],
    "userBoardGames": [
      {
        "id": 7,
        "date": "2024-05-18T02:23:46.608+00:00"
      }
    ],
    "tags": []
  },
  {
    "id": 10,
    "thumbnailUrl": "https://cf.geekdo-images.com/8kl6m6m_unthBPw9SxoDQQ__thumb/img/vK6rBE3ZjolzG6jEVxJj49MBIc4=/fit-in/200x150/filters:strip_icc()/pic6973677.png",
    "imageUrl": "https://cf.geekdo-images.com/8kl6m6m_unthBPw9SxoDQQ__original/img/FtecAcFxPelZCfbWhZlo85uF2Rg=/0x0/filters:format(png)/pic6973677.png",
    "name": "셀레스티아10",
    "description": "예시용 설명",
    "rating": 0,
    "ratingCount": 0,
    "minPlayers": 2,
    "maxPlayers": 6,
    "playtime": 30,
    "ageLimit": 8,
    "difficulty": 3,
    "rule": "gg",
    "extraVideo": "temp",
    "likes": 0,
    "picked": false,
    "boardGameCategories": [
      {
        "id": 19
      },
      {
        "id": 20
      }
    ],
    "userBoardGames": [],
    "tags": []
  }
]

카테고리 보드게임 조회

  • description: 카테고리 필터를 통해 보드게임들을 조회한다.
    사용자 인증정보를 요청 헤더에 포함할 수 있다.
  • Method: GET
  • URI: /api/boardgames
  • parameters:
    - category: 필터링 할 카테고리의 이름
  • 요청 예시: /api/boardgames?category=롤플레잉
  • 응답 예시:
[
  {
    "id": 3,
    "thumbnailUrl": "https://cf.geekdo-images.com/8kl6m6m_unthBPw9SxoDQQ__thumb/img/vK6rBE3ZjolzG6jEVxJj49MBIc4=/fit-in/200x150/filters:strip_icc()/pic6973677.png",
    "imageUrl": "https://cf.geekdo-images.com/8kl6m6m_unthBPw9SxoDQQ__original/img/FtecAcFxPelZCfbWhZlo85uF2Rg=/0x0/filters:format(png)/pic6973677.png",
    "name": "셀레스티아3",
    "description": "예시용 설명",
    "rating": 0,
    "ratingCount": 0,
    "minPlayers": 0,
    "maxPlayers": 0,
    "playtime": 0,
    "ageLimit": 0,
    "difficulty": 0,
    "rule": null,
    "extraVideo": null,
    "likes": 0,
    "picked": true,
    "boardGameCategories": null,
    "userBoardGames": null,
    "tags": []
  },
  {
    "id": 4,
    "thumbnailUrl": "https://cf.geekdo-images.com/8kl6m6m_unthBPw9SxoDQQ__thumb/img/vK6rBE3ZjolzG6jEVxJj49MBIc4=/fit-in/200x150/filters:strip_icc()/pic6973677.png",
    "imageUrl": "https://cf.geekdo-images.com/8kl6m6m_unthBPw9SxoDQQ__original/img/FtecAcFxPelZCfbWhZlo85uF2Rg=/0x0/filters:format(png)/pic6973677.png",
    "name": "셀레스티아4",
    "description": "예시용 설명",
    "rating": 0,
    "ratingCount": 0,
    "minPlayers": 0,
    "maxPlayers": 0,
    "playtime": 0,
    "ageLimit": 0,
    "difficulty": 0,
    "rule": null,
    "extraVideo": null,
    "likes": 0,
    "picked": true,
    "boardGameCategories": null,
    "userBoardGames": null,
    "tags": []
  }
]

보드게임 상세보기

  • description: 특정 보드게임에 대한 정보들을 모아본다.
  • Method: GET
  • URI: /api/boardgame/{보드게임id}
  • 요청 예시: /api/boardgames/1
  • Response:
{
  "id": 1,
  "thumbnailUrl": "https://cf.geekdo-images.com/8kl6m6m_unthBPw9SxoDQQ__thumb/img/vK6rBE3ZjolzG6jEVxJj49MBIc4=/fit-in/200x150/filters:strip_icc()/pic6973677.png",
  "imageUrl": "https://cf.geekdo-images.com/8kl6m6m_unthBPw9SxoDQQ__original/img/FtecAcFxPelZCfbWhZlo85uF2Rg=/0x0/filters:format(png)/pic6973677.png",
  "name": "셀레스티아1",
  "description": "예시용 설명",
  "rating": 0,
  "ratingCount": 0,
  "minPlayers": 2,
  "maxPlayers": 6,
  "playtime": 30,
  "ageLimit": 8,
  "difficulty": 3,
  "rule": "gg",
  "extraVideo": "temp",
  "likes": 1,
  "picked": false,
  "boardGameCategories": [
    {
      "id": 1
    },
    {
      "id": 2
    }
  ],
  "userBoardGames": [
    {
      "id": 7,
      "date": "2024-05-18T02:23:46.608+00:00"
    }
  ],
  "tags": []
}

오늘의 PICK 순위 보기

  • description: 오늘의 PICK 순위 TOP 10을 가져온다.
  • Method: GET
  • URI: /api/boardgames/today-pick
  • 요청 예시: /api/boardgames/today-pick
  • Response:
{
  "id": 1,
  "thumbnailUrl": "https://cf.geekdo-images.com/8kl6m6m_unthBPw9SxoDQQ__thumb/img/vK6rBE3ZjolzG6jEVxJj49MBIc4=/fit-in/200x150/filters:strip_icc()/pic6973677.png",
  "imageUrl": "https://cf.geekdo-images.com/8kl6m6m_unthBPw9SxoDQQ__original/img/FtecAcFxPelZCfbWhZlo85uF2Rg=/0x0/filters:format(png)/pic6973677.png",
  "name": "셀레스티아1",
  "description": "예시용 설명",
  "rating": 0,
  "ratingCount": 0,
  "picked": true,
  "tags": []
}

추천 보드게임

description:

  • 유저가 pick한 게임들의 카테고리들을 가져와 누적 점수표를 만든다.
    점수표를 기준으로 나머지 보드게임들의 점수를 매겨 상위 10개를 반환한다.
    10개 미만 시 랜덤으로 채운다.
    비로그인 or pick한게 없을 시에도 랜덤으로 채워 반환한다.

Method

  • GET

URI

  • /api/boardgames/recs
  • 요청 예시: /api/boardgames/recs

Response:

[
    {
        "id": 17,
        "thumbnailUrl": "https://cf.geekdo-images.com/0xqF_KyOb7V26Lu5YT3fxw__thumb/img/ABTwzzMGekkz2jVl01LC4789TcQ=/fit-in/200x150/filters:strip_icc()/pic6699821.jpg",
        "imageUrl": "https://cf.geekdo-images.com/0xqF_KyOb7V26Lu5YT3fxw__original/img/uqxMcj1QPt-U34drYdL6mmv2eos=/0x0/filters:format(jpeg)/pic6699821.jpg",
        "name": "어스",
        "description": "상품을 배송하고 건물을 짓고,  다른 사람들보다 당신에게 더 도움이 되는 역할을 선택하세요",
        "rating": 484.0,
        "ratingCount": 0,
        "minPlayers": 1,
        "maxPlayers": 5,
        "playtime": 60,
        "ageLimit": 13,
        "difficulty": "중수",
        "rule": "https://www.youtube.com/embed/EKQb3MX1el8",
        "extraVideo": "https://www.youtube.com/embed/OOEdQUktDao",
        "likes": 0,
        "picked": false,
        "boardGameCategories": [
            "카드게임",
            "전략게임"
        ],
        "userBoardGames": [],
        "tags": [
            "자원 승점",
            "타일 놓기",
            "환경"
        ]
    },
  // 다른 보드게임들...
]

Pick on/off

  • description: 로그인한 유저에 대해 pick on/off 요청을 보낼 수 있다.
  • Method: POST
  • URI: /api/pick/{boardGameId}
  • 요청 예시: /api/pick/1
  • Response:
{
  "picked": true
}

MyPick 리스트 조회

  • description: 로그인한 유저에 대해 MyPick 리스트를 반환한다.
  • Method: GET
  • URI: /api/pick
  • 요청 예시: /api/pick
  • Response:
[
  {
    "id": 1,
    "thumbnailUrl": "https://cf.geekdo-images.com/8kl6m6m_unthBPw9SxoDQQ__thumb/img/vK6rBE3ZjolzG6jEVxJj49MBIc4=/fit-in/200x150/filters:strip_icc()/pic6973677.png",
    "imageUrl": "https://cf.geekdo-images.com/8kl6m6m_unthBPw9SxoDQQ__original/img/FtecAcFxPelZCfbWhZlo85uF2Rg=/0x0/filters:format(png)/pic6973677.png",
    "name": "셀레스티아1",
    "description": "예시용 설명",
    "rating": 0,
    "ratingCount": 0,
    "minPlayers": 0,
    "maxPlayers": 0,
    "playtime": 0,
    "ageLimit": 0,
    "difficulty": 0,
    "rule": null,
    "extraVideo": null,
    "likes": 0,
    "picked": true,
    "boardGameCategories": null,
    "userBoardGames": null,
    "tags": []
  }
]

User 정보 가져오기

  • description: 로그인한 유저에 대해 사용자 정보를 반환한다.
  • Method: GET
  • URI: /api/user
  • 요청 예시: /api/user
  • Response:
{
  "id": 2, // 사용자 DB 식별 번호
  "code": "kakao_3477934666", // 사용자 식별 코드
  "profileImage": "http://k.kakaocdn.net/dn/blt0qi/btsF5E32BWI/dDmvFXnJlFJ0UnedbTilYK/img_640x640.jpg",
  "nickname": "안준성",
  "role": "USER", // 사용자 권한
  "userBoardGames": [] // 사용자가 pick한 보드게임들
}

Top10 리스트 조회

description

  • 각종 filter에 대한 Top10 리스트를 반환한다.
  • ex. "둘이서 하기 좋은 보드게임"

Method

  • GET

URI

  • /api/boardgames/list?filter=
  • filter 도메인: "difficulty"(쉬운 게임), "players"(단체 게임), "duo"(2인 게임)
  • 요청 예시:
    api/boardgames/list?filter=difficulty
    api/boardgames/list?filter=players
    api/boardgames/list?filter=duo

Response:

[
  {
    "id": 5,
    "thumbnailUrl": "https://cf.geekdo-images.com/wKwRk0wYBcrtLAfgn4PCdg__thumb/img/mJNzYNKvYWDlaaD12V32BJ453d0=/fit-in/200x150/filters:strip_icc()/pic6624445.png",
    "imageUrl": "https://cf.geekdo-images.com/wKwRk0wYBcrtLAfgn4PCdg__original/img/Wpp0vzsVe4HxXGUqiZ1hDvwAHZU=/0x0/filters:format(png)/pic6624445.png",
    "name": "투 매니 본즈",
    "description": "마지막 보스 대결로 가는 길에 서사시적인 모험에서 독특한 주사위를 투수하세요",
    "rating": 227, // 현재 안 쓰는 정보
    "ratingCount": 0, // 현재 안 쓰는 정보
    "minPlayers": 1,
    "maxPlayers": 4,
    "playtime": 75,
    "ageLimit": 12,
    "difficulty": "고수",
    "rule": "유튜브 링크",
    "extraVideo": "유튜브 링크",
    "likes": 0, // pick 횟수
    "picked": false, // 현재 사용자가 해당 보드게임의 pick 여부
    "boardGameCategories": [
      "롤플레잉",
      "협력게임"
    ],
    "userBoardGames": [], // 아직은 필요 없는 정보
    "tags": [
      "모험",
      "판타지",
      "주사위"
    ]
  },
  // ... 다른 보드게임들
]

OO과 비슷한 보드게임

description

  • PathValue로 받은 보드게임id에 대해 카테고리 기준으로 비슷한 보드게임들을 반환한다.
  • 보드게임이 여러 카테고리에 속해 있으면 많이 겹치는 순으로 정렬된다.

Method

  • GET

URI

  • /api/boardgames/similar/{boardGameId}
  • 요청 예시:
    api/boardgames/similar/1

Response:

[
  {
    "id": 9,
    "thumbnailUrl": "https://cf.geekdo-images.com/sZYp_3BTDGjh2unaZfZmuA__thumb/img/veqFeP4d_3zNhFc3GNBkV95rBEQ=/fit-in/200x150/filters:strip_icc()/pic2437871.jpg",
    "imageUrl": "https://cf.geekdo-images.com/sZYp_3BTDGjh2unaZfZmuA__original/img/7d-lj5Gd1e8PFnD97LYFah2c45M=/0x0/filters:format(jpeg)/pic2437871.jpg",
    "name": "글룸헤이븐",
    "description": "전략적 카드 플레이로 괴물을 정복하세요. 당신의 유산을 남기기 위한 당신의 탐구를 완수하세요",
    "rating": 1,
    "ratingCount": 0,
    "minPlayers": 1,
    "maxPlayers": 4,
    "playtime": 90,
    "ageLimit": 14,
    "difficulty": "고수",
    "rule": "https://www.youtube.com/embed/Wck7YRZ77Xk",
    "extraVideo": "https://www.youtube.com/embed/Si3XQuYNj-A",
    "likes": 0,
    "picked": false,
    "boardGameCategories": [
      "전략게임",
      "협력게임"
    ],
    "userBoardGames": [],
    "tags": [
      "모험",
      "탐험",
      "판타지"
    ]
  },
  // ... 다른 보드게임들
]

이런 보드게임은 어떠세요?

description

  • 누적 pick을 가장 많이 받은 보드게임 10개를 반환한다.

Method

  • GET

URI

  • /api/boardgames/suggestion
  • 요청 예시:
    /api/boardgames/suggestion

Response:

[
    {
        "id": 59,
        "thumbnailUrl": "https://cf.geekdo-images.com/YEUOppe56fm-B-77407a2Q__thumb/img/L9zvscdhFlsUAJslmteB3JMHmKg=/fit-in/200x150/filters:strip_icc()/pic792277.jpg",
        "imageUrl": "https://cf.geekdo-images.com/YEUOppe56fm-B-77407a2Q__original/img/aIXlMR7X5mGAdI06LV7n33ZLThU=/0x0/filters:format(jpeg)/pic792277.jpg",
        "name": "서바이브!",
        "description": "이 2010년 판은 1982년 원작 'Survive!'의 재판이 아닌 추가적인 조각과 룰을 통해 'Survive!'와 'Waddington's Escape from Atlantis'를 플레이할 수 있도록 한 판이며,  이에 더불어 'Survive: Escape from Atlantis! - Dolphins ,  Dive Dice Mini Expansion'이 포함되어 있습니다.",
        "rating": 866.0,
        "ratingCount": 0,
        "minPlayers": 2,
        "maxPlayers": 4,
        "playtime": 50,
        "ageLimit": 8,
        "difficulty": "왕초보",
        "rule": "https://www.youtube.com/embed/EiGxIvPcmtc",
        "extraVideo": "https://www.youtube.com/embed/null",
        "likes": 2,
        "picked": false,
        "boardGameCategories": [
            "기억력",
            "배팅게임"
        ],
        "userBoardGames": [
            {
                "id": 104,
                "date": "2024-05-23T05:30:11.783+00:00"
            },
            {
                "id": 372,
                "date": "2024-05-26T17:49:16.531+00:00"
            }
        ],
        "tags": [
            "전략",
            "블러핑",
            "기억력"
        ]
    },
  // ... 다른 보드게임들
]
profile
안준성
안녕하세요

0개의 댓글