2023-09-16 백엔드 V2 라우트 정리 회의

[scarf005]

이전 회의	#767
장소	3층
기간	2023-09-16 09:00/12:00
참석자	@scarf005 @Jiwon-Woo @nyj001012
목표	V2 라우트 전체 라우트, query, body, 반환값 형식 통일 및 단순화

참고자료

• https://old.reddit.com/r/node/comments/bmwdl6/what_are_your_goto_resources_for_rest_api_design/
• https://cloud.google.com/apis/design?hl=ko
• https://github.com/typicode/json-server

결론

• 되도록이면 플랫 경로 사용
• 도서 정보 경로는 bookmetas 사용
• 고민될때는 github rest API 참고 (골-든 정답)

[scarf005]

도서 정보 경로 이름 정하기

• bookmetas
• book-metas -> github도 쓰더라, but query로 book-metas를 줄 일이 있을까?
• book_metas js에서는 스네이크, URL에서는 -, 변환과정이 살짝 복잡해질듯, ts-rest에서는 문제없음

[scarf005]

저희 논의했는데 합의점 적는것을 깜빡했네요 kebab-case로 하기로 정해진 것이죠?

[Jiwon-Woo]

집현전 데브채널에서 투표한 결과 kebab-case로 결정했습니다!

[scarf005]

플랫 경로 사용 여부

계층 경로 사용시

• /bookmeta/{metaId}/book/{id}/

Github Rest API와 같이 사용

/{user}/{repo} -> /{book}/{callnumber}/

예시: https://42library.kr/info/936

PATCH /books/936/I28.13.v1.c1/likes

플랫 경로 사용시

• /bookmetas/{id}
• /books/{id}

PATCH /books/3

참고자료

• https://stackoverflow.com/questions/2150171/how-should-a-rest-url-schema-look-like-for-a-tree-hierarchy

[scarf005]

되도록이면 플랫 경로 사용

[scarf005]

/mypage/{자원}/{id} vs /users/{사용자 ID}/{자원}/{id}

예시

id 123인 사용자의 리뷰 조회: GET /123/reviews/

장점

• 사서와 사용자가 동일한 API 사용 가능
• 복잡도 감소

단점

• 내 정보 가져올때 쿠키에 요청자 ID가 있음에도 /users/{id}/자원/{id} 형식으로 요청해야 함
• 프론트엔드에서는 쿠키에 ID를 저장하므로 불필요한 API 요청 및 복잡도 증가

참고자료

https://docs.github.com/en/rest/activity/starring?apiVersion=2022-11-28

[Jiwon-Woo]

• users/{사용자 ID}/{자원}/{id}

[scarf005]

GET /users/123/reviews

[Jiwon-Woo]

mypage 대신 me나 user 같은 경로를 써보는 건 어떨까요?

[scarf005]

• me: 경로가 짧아져서 단순함
• user와 users: 통일성이 올라가나 처음 보고 헷갈릴수도

[scarf005]

다수결의 동의로, user를 택했습니다.

[scarf005]

/{isbn} /{callnumber}을 경로로 사용하기?

isbn이 존재하지 않는 경우도 존재

MariaDB [jip_dev]> select title, isbn from book_info where isbn is NULL;
+-----------------------------------------------------------------------------------------------------------------------+------+
| title                                                                                                                 | isbn |
+-----------------------------------------------------------------------------------------------------------------------+------+
| 학교개혁은 왜 실패하는가 (교육변화의 새로운 의미와 성공원리)                                                          | NULL |
| (윈도우즈)API 정복 vol 1.                                                                                             | NULL |
| 중세의 예술과 사회                                                                                                    | NULL |
| 4차 산업혁명에 대응한 직업교육훈련기관 신산업분야 교원운영 패러다임 전환 연구(2020)                                   | NULL |
| 눈 떠보니 선진국                                                                                                      | NULL |
| 나무                                                                                                                  | NULL |
| Whale done! : the power of positive relationships                                                                     | NULL |
| THE C PROGRAMING LANGUAGE                                                                                             | NULL |
| C PROGRAMMING A MODERN APPORACH                                                                                       | NULL |
| Introduction to Algorithms                                                                                            | NULL |
| Data Structures and Algorithms in Python                                                                              | NULL |
| Cracking the Coding Interview: 189 Programming Questions and Solutions                                                | NULL |
| 이것이 C++ 이다                                                                                                       | NULL |
| 위대한 IT 영어                                                                                                        | NULL |
+-----------------------------------------------------------------------------------------------------------------------+------+
14 rows in set (0.005 sec)

사용례?

-> 사실 프론트엔드에서만 해주어도 됨

[scarf005]

백엔드와 프론트 URL 괴리는 얼마나 허용이 될까

[scarf005]

경로 입력값, 반환값 통일

입력값

반환값

1. 개별 정보 가져오기 /{id}
2. 여러 정보 가져오기 /

모든 날짜를 Date 형식 string으로 반환하자

/api/bookmetas/{id}

개별 도서(book)랑 도서 정보(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"
	  "copies": [
			{
	      		"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"
	}
}

/api/books

페이지네이션 적용시에는?

{
	"items": [
	
	"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"
		}
	],
	"pagniation": {
		"first": 0,
		"last": 4,
	}
}

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

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

[nyj001012]

meta 대신 pagination이나 page로 바뀌었으면 합니다

[scarf005]

• V2 API 반환값 통일하기 #774

[scarf005]

커서 vs 오프셋 페이지네이션

커서

1000개중에서 10개씩 5페이지 가져옴 -> 그 아이템의 인덱스 저장
6페이지 가져올때는 인덱스에서 10개만 호출

총 쿼리 크기: 1000 + 10

오프셋

1000 + 1000

[scarf005]

reviews, bookmetas, books, likes, lendings, reservations, users, user