API 기능 고도화

[junha-ahn]

Description

현재 첫번째 개발 사이클 완료를 목표로 최소한의 기능만 구현했습니다.

실제 프론트엔드에서 사용 가능한 API를 만들어주세요.

• USER
• Event
• Reservation
• Bookmark

기능을 새롭게 추가하는게 아니라, 실제로 사용 가능한 정보를 담고, 그에 맞는 API 만 만들어주시면 됩니다.

• 예를들어 좌석 예약 기능을 추가하는게 아니라, 공연 리스트, 예매 리스트 조회에 페이지네이션을 추가하는 경우

해당 이슈에 의존성을 가집니다

• 회원 기능 구현 #4
• PK Int vs Long #50
• 컨벤션 정의: Time  #39
• 레이어간 데이터 전달 형식 정의 #36
  • Wiki - HTTP Response 형식 준수
  • @ExceptionHandler - Custom Error
• 로그 기능 구현 #78
• Validation 구현 #40
• API Docs 자동화 #37
• JPA 제약조건 명시 #82

To do

• 데이터베이스 설계 (ERD 작성)
• API 명세 설계
• 기능 구현 (위 의존성에 정의된 사항을 모두 준수)

Test Checklist

• Test Coverage over 80%

[ParkJeongseop]

ERD

ERD

현재 구성에 맞게 ERD를 작성하였습니다.

[junha-ahn]

1. booked_at 은 필요없어보입니다. created_at 으로 대체 가능
   • 모든 테이블에 명시없이 created_at, updated_at은 기본으로 생성/사용합니다.
2. role은 현재 필요 없습니다.
3. pw => password
4. username 생성
5. email varchar(320) 인 이유가 있습니까? (이메일은 320자까지 가능한가요? 아니라면 255로 통일해도 좋을것 같네요)

---

해당 청사진을 보고 설계 부탁드립니다!

• 좌석은 고려할 필요 없습니다

해당 ISSUE의 ERD는 프론트엔드에서 실제로 사용할 데이터를 포함해야 합니다. (예를들어 공연리스트를 띄워야할탠데, thumbnail path 등...)

물런 사이드 프로젝트이기 때문에 굳이 모든 정보를 포함할 필요는 없지만, 최소한의 데이터는 포함해주세요. (간단하면서 복잡하게)

가장 간단하게 프론트엔드를 구성한다면 어떻게 할까? 정도를 생각하시면서 하면 좋을 것 같네요.

참고

• festa (IT 행사 티켓팅 사이트)
• https://blog.naver.com/trric/222729249130

[ParkJeongseop]

이메일 주소 최대길이가 320자입니다.
what-is-email

로컬 부분은 이메일 메시지의 최종 위치를 서버에 알려줍니다. 문자, 숫자, 특정 문장 부호(밑줄 등)가 포함될 수 있습니다. 이메일 주소의 권장 길이는 254자로 제한되지만 (로컬 부분 및 도메인을 포함한) 최대 문자수는 320자입니다.

[ParkJeongseop]

ERD 업데이트 하였습니다.

[junha-ahn]

1. 이벤트에 content 첨부 부탁드립니다 (긴 설명입니다)
2. 전화번호 타입 고려 부탁드립니다. (tinyint는 255까지 지원하는 자료형입니다. (11)은 db int zerofill 키워드를 통해 검색 부탁드립니다)
3. 우편번호도 동일합니다

전화번호 관련 자료

• Which is best data type for phone number in MySQL and what should Java type mapping for it be?
• https://www.youtube.com/watch?v=PiMlUjQP-JM
• https://okky.kr/questions/1176301#answer-614827
• https://www.phpschool.com/gnuboard4/bbs/board.php?bo_table=qna_db&wr_id=190011&sca=&sfl=wr_subject%7C%7Cwr_content&stx=varchar+%C0%CE%B5%A6%BD%BA&sop=and
• MySQL 검색속도 : int 와 varchar 누가 더 빠르냐?
• 국가 코드는 고려하지 않습니다.

[ParkJeongseop]

수정하였습니다.

[junha-ahn]

INT Null OR MAX value 에 대해

• https://stackoverflow.com/questions/21286215/how-can-i-include-null-values-in-a-min-or-max
• https://stackoverflow.com/questions/28834499/is-it-better-to-use-null-or-1-to-indicate-infinite-in-integer-columns-of
• https://stackoverflow.com/questions/15578050/null-vs-infinity-in-postgresql-range-types
• https://saturncloud.io/blog/how-do-null-values-affect-performance-in-a-database-search/
• https://www.sqlservercentral.com/blogs/null-values-impact-the-performance-of-max-and-min

[junha-ahn]

개발 시나리오

Bookmark API Upgrade (각 커밋에 테스트 코드부터 작성 권장)

• 1. JWT Validation 적용 (회원 기능 구현 #4)
• 2. advanced-api-data-convention (컨벤션 정의: Time  #39, PK Int vs Long #50, JPA 제약조건 명시 #82)

Time Convention은 모든 Time 관련 데이터를 OffsetDateTime 형식으로 변경 (그외 타입 사용 X)
PK는 모두 INT를 사용 (Long 사용 금지)
DB 제약조건, 외래키 관계 명시

• 3. 모든 API에 Request Data Validation 적용 (Validation 구현 #40)
• 4. Custom Error 구현 (레이어간 데이터 전달 형식 정의 #36)
• 5. 로깅 구현 (로그 기능 구현 #78)
• 6. API 명세 설계 및 구현 (API Docs 자동화 #37)
  - 실제 사용 가능화 (ex: pagenation, search 등)
  - 참고: API 기능 고도화 #52 (comment)

그외) 향후 쿼리 및 DB 인덱스 설계 (부하 테스트와 함께 향후 Git Issue화)
- Real MySQL 및 업무에 바로 쓰는 SQL 튜닝 책 드릴 예정입니다.

위 시나리오 번호마다 커밋 하나씩 사용하시면 될 것 같습니다.

[junha-ahn]

@minjun3021 ERD에 따른 수정 부탁드립니다.

https://www.erdcloud.com/d/YbadkYrimpCu5Kois

변경사항

• user.pw => user.password
• event.title => event.name (= name으로 통일)
• 그 외 ERD 준수

참고: https://festa.io/events

[junha-ahn]

API 고도화 마무리 작업

• 출처: https://sanghaklee.tistory.com/57

현재 위반사항

• 2.1. 마지막에 / 포함하지 않는다. : GET events/

추가사항

• 3. Set HTTP Headers
  • 3.1. Content-Location (우선순위 낮음)
  • 3.2. Content-Type
  • 3.4. Link
• 4. Use HTTP methods
  • 4.2. OPTIONS, HEAD, PATCH를 사용하여 완성도 높은 API를 만든다.
• 5.2. HTTP status만으로 상태 에러를 나타낸다 (moreinfo 부분을 openDocs에 error_code 설명란으로 할 수 있게 추가)
• 6.1. 성공 응답은 2XX로 응답한다. (200,201,204 구분, 405 등도..)
• 7. Use HATEOAS
• 8. Paging, Ordering, Filtering, Field-Selecting
  • 8.1. Paging
  • 8.2. Ordering
  • 8.3. Filtering
  • 8.4. Field-Selecting
• 9. Versioning

기타: API Docs

위 사항 중 API Docs 노출 가능한 것은 하기

• 추가로, HTTP Response Custom Error Code 노출하기

[ParkJeongseop]

논의 하고자 하는 부분이 있는데 페이지네이션 구현과정에 REST API 규격대로면 HTTP헤더 Link에 페이지네이션 정보를 넣는것과 HATEOAS의 links 항목에 넣는것, 두군데 모두 넣는것이 위 언급하신 웹문서에 나와있습니다.
찾아보니 HTTP 헤더 Link 는 HTTP API 표준이고, HATEOAS HAL은 REST API의 표준인것 같습니다.
저희는 어떤 표준을 준수할지 혹은 둘다 준수할 것인지, 또 해당 표준만으로는 전체 데이터 건수를 알수 없어서 결국엔 표준방법을 사용하기 이전과 같이 Response Body에 페이지네이션 정보가 추가로 들어가야하는데 해당 표준들이 과연 효율적인지에 의문입니다.

HATEOAS
HATEOAS를 모르면 당신이 알고 있는 REST API는 REST API가 아니라고 장담할게요.
[ Rest API ] HATEOAS 를 써야 할까 ?

또한 저희는 OPEN API를 제공하는 것이아닌 자체 서비스를 위한 API를 개발하는데 API문서 URI를 제공해야하는지도 궁금합니다.

[junha-ahn]

[ Rest API ] HATEOAS 를 써야 할까 ?

하지만 RESTful 을 충족하는 것이 신성한 것으로 간주돼서는 안되며
레벨 2의 서비스가 되는 것이 해당 API 가 레벨 3 의 API 보다 열등하다는 것을 의미하지 않는다.
HATEOAS 를 구현할지 말지는 API 의 본질과 노력의 가치 여부에 달려있다

해당 내용이 매우 좋네요. 본문 내용도 공감 됩니다

해당 표준만으로는 전체 데이터 건수를 알수 없어서 결국엔 표준방법을 사용하기 이전과 같이 Response Body에 페이지네이션 정보가 추가로 들어가야하는데 해당 표준들이 과연 효율적인지에 의문입니다. 또한 저희는 OPEN API를 제공하는 것이아닌 자체 서비스를 위한 API를 개발하는데 API문서 URI를 제공해야하는지도 궁금합니다

'비효율'에 대한 내용 모두 맞습니다. 하지만 해당 프로젝트는 사이드 프로젝트이며, HATEOAS를 구현 하는 것 자체에 의미를 두고 싶습니다. 다시말해 표준을 지키는것에 큰 의미를 부여하지는 않고, (구현해본적 없는) 해당 기능을 구현해보는 경험에 의미를 두고 싶습니다. 그 과정에서 겪는 문제점이나, 장점과 단점 또는 불편함, 비효율성을 체험하기만 해도 충분한 의미가 있다고 생각합니다.

따라서 제 의견은 "구현해보자"입니다

[ParkJeongseop]

좋습니다.

9번항목의 버저닝은

웹 서버의 reverse-proxy 기능을 활용한다
웹 APP 서버의 라우팅은 버저닝을 제외하고 개발한다. /users, /posts

라고 되어있어 인프라팀에서 nginx 웹서버에서 처리해야될것같습니다.

확인부탁드립니다.