V2 API 반환값 통일하기

[scarf005]

담당

@scarf005

• bookmetas
• books

@Jiwon-Woo

• reviews

@honeyl3ee

• likes

@nyj001012

• users

고난이도, 후순위

• lendings
• reservations
• tags

예시: pubdate -> publishedAt

1개, 1개 쿼리(나), N개 쿼리

[scarf005]

reservation

/books/{id}?lendings=&reservations=

/books/{id}/reservations

/reservations/{id}

/reservations/{book-meta}

[scarf005]

Stock (예시)

/api/stock/search

• /api/books/search 에 통합

[scarf005]

BookMetas

• bookInfoId, bookinfo 필드와 겹침 ->

{
"id": 2,
  "title": "TCP IP 윈도우 소켓 프로그래밍",
  "author": "김선우",
  "publisher": "한빛아카데미",
  "isbn": "9788998756444",
  "image": "https://image.kyobobook.co.kr/images/book/xlarge/444/x9788998756444.jpg",
  "categoryId": 2,
  "category": "네트워크",
"pubishedAt": "2022-07-09-22:49:33",
  "updatedAt": "2022-07-09-22:49:33"
}

	{
    		"id": 3,
    		"donator": null,
        "callSign": "C5.13.v1.c2",
    		"status": "ok",
    		"updatedAt": "2022-07-09-22:49:33"
	}

/api/books/{id}

개별 도서(book)랑 도서 정보(bookinfo)이 정보가 지나치게 겹침

{
	"bookmeta": {
      "id": 2,
      "title": "TCP IP 윈도우 소켓 프로그래밍",
      "author": "김선우",
      "publisher": "한빛아카데미",
      "isbn": "9788998756444",
      "image": "https://image.kyobobook.co.kr/images/book/xlarge/444/x9788998756444.jpg",
      "categoryId": 2,
      "category": "네트워크",
	  "pubishedAt": "2022-07-09-22:49:33",
      "updatedAt": "2022-07-09-22:49:33"
	},
	"book": {
		"id": 3,
		"donator": null,
		"callSign": "C5.13.v1.c2",
		"status": "ok",
		"updatedAt": "2022-07-09-22:49:33"
	}
}

[scarf005]

카테고리: 어디에서는 id, 어디에서는 문자열

createdAt: Date
pubdate: "YYYYMMDD" 형식 string -> pubishedAt로 변경

[scarf005]

정리 가이드

플랫 경로를 지향하기 위해 {id}만으로 조회 가능하게 하자

/books/info/{bookInfoId}/like -> /likes/{id}

여러 정보를 가져온다면 중첩 형태를 쓰자

ko

{
	bookId: 1
	bookMetaId: 2
	categoryId: 3
	category: "과학"
	// book 필드...
	// bookMeta 필드...
}

ok

{
	// book 스키마 형태 유지
	book: {
		id: 1
		// book 필드...
	},
	book-meta: {
		id: 2
		// bookMeta 필드...
	},
	category: {
		id: 3
		name: "과학"
	},
}

수정: ID 기반 쿼리는 지나치게 복잡하여 처음 아이디어처럼 중첩 반환을 사용해주시면 될 것 같습니다

[Jiwon-Woo]

Reviews

1. GET /api/reviews/my-reviews -> /api/v2/user/reviews

2. GET /api/book-info/{bookInfoId}/reviews 삭제, GET /api/v2/reviews 에 통합

• query에 bookInfoId(bookMetaId) 추가

3. PUT /api/v2/reviews/{reviewsId} -> PATCH /api/v2/user/reviews

• body에 disabled만 받을 수 있게

  body
  {
    "visible": true
  }

4. PATCH와 DELETE에서 사용하는 reviewsId (복수)를 reviewId (단수) or id 로 변경

5. POST /api/v2/reviews 에서 query 말고 body에 bookInfoId(bookMetaId) 넣기

body
{
  "bookInfoId": 1,
  "content": "리뷰 내용"
}

6. GET /api/v2/reviews

• nickname은 react query를 이용해서 캐싱할 예정이므로 userId만 보냄

{
  "items": [
    {
      "id": 0,
      "userId": 1,
      "bookInfoId": 0,
      "createdAt": "2023-09-16T02:25:55.974Z",
      "title": "string",
      "content": "string",
      "visible": boolean
    }
  ],
  "meta": {
    "totalItems": 42,
    "totalPages": 5
  }
}

[Jiwon-Woo]

질문

• limit에서 perPage로 통일되나요?
• disabled에서 visibility로 통일되나요?

[scarf005]

visible: boolean 어떨까요?

[nyj001012]

Users

API 명세에서 타입 혼용

• role의 데이터 타입 string -> enum(literal union)
• overDueDay의 데이터 타입 string -> number
• intraId의 데이터 타입 string -> number

[scarf005]

role: "user" | "cadet" | "librarian" | "staff" 식으로 string을 반환해도 괜찮을것 같아요
reservedNum: number로
penaltyEndDate: Date string으로

[nyj001012]

• overDueDay는 프론트엔드에서 처리

[honeyl3ee]

Likes

플랫 경로 사용

• POST '/books/info/{bookInfoId}/like' -> /likes/{id}'
• GET '/books/info/{bookInfoId}/like' -> /likes/{id}'
• DELETE '/books/info/{bookInfoId}/like' -> /likes/{id}'

중첩 형태 사용

• POST '/books/info/{bookInfoId}/like'

{
  "userId": 1,
  "bookInfoId": 0
} 

{
	user: {
		id: 1
	},
	book-meta: {
		id: 0
	},
}

• GET '/books/info/{bookInfoId}/like'

{
  "bookInfoId": 0,
  "isLiked": true,
  "likeNum": 1
} 

{
	book-meta: {
		id: 0
	},
	isLiked: ture
	likeNum: 1
}

[scarf005]

github의 starring api를 벤치마킹하면

POST /user/likes/{book-metas-id}
DELETE /user/likes/{book-metas-id}
GET /user/likes

문제점: 다른 모든 경로와 달리 likes경로만 id 경로가 다른 자원의 id임

[Jiwon-Woo]

POST /user/likes, body { "book-meta-id": 1 }
DELETE /user/likes/{like_id}
GET /user/likes