API를 설계하며 고민 한 것들을 적어 놓는 공간.
백엔드가 고려해야 될 것 들
- Restful 한 API 설계를 했는지
- 문서화가 좋은지 사용법이 명확한지 (외부 SDK로 배포하더라도 괜찮은 정도의 퀄인지 생각해보기)
- API가 UI에 종속되지 않아야 한다 -> UI가 바뀌더라도, 사용 할수 있는가
- 백엔드의 1차적인 유저는 프론트라는 점
- 아 이사람 api 잘 짜주던데~
좋은 API 문서 예시
네이버 NCloud (링크)
- 상태코드를 존중한 Restful 한 작성
NHN (링크)
- 모든 API를 200으로 처리함 (링크)
- 성공과 실패에 대한
Redoc 활용 좋은 예시
- Redoc에서 상태코드를 지켜서 문서화 (링크)
Permission 범위
작은 범위의 permission 체크 (공통 레벨)
- 해당 모델에 대한 체크
- user.user_type에 대한 체크에 대한 permission -> user의 service에서 검증
- ex) 유저가 고객 유저의 type인가? -> 작은 범위
큰 범위의 permission 체크
- 해당 모델이 타 모델과의 정합성 까지 체크
- 자원 객체의 주인이 user.user_id 인지에 대한 permission -> 해당 app의 service에서 검증ex) 유저의 상품이 고객 유저의 상품인가? -> 큰 범위
BaseAPI
웹 서비스 페이지를 구현하는데 필요한 or Payload에 포함되는 or 백엔드-프론트 간의 규칙 등의 기본 정보를 BaseAPI로 내려줄 수 있음
case 1) 웹 서비스 페이지 구현시 필요 정보 (dropdown / checkbox 목록) -> BE에서 영어로 내려줌 (프론트는 알아서 영어를 한글로 치환하여 사용, 영어가 아니더라도 특정 DB 값)
case 2) Payload에 포함하여 보낼 정보 -> BE에서 obj 객체에 대한 id, name 등을 내려줌
case 3) BE-FE 간의 규칙
- API Docs나 부가적인 Docs를 통해 명시 (ex. 어떤 조건에 대해서는 해당 문자열을 사용해야 함)
- 백과 프론트는 각자 enum을 만들어 관리
HTTP 메소드의 PATCH vs PUT의 차이
- patch와 put을 나누는 기준은 자원에 대한 일괄 수정을 보장하는지, 부분 수정을 보장하는지에 대한 여부
- 프론트에서 던지는 payload에 대해 있고 없고의 설명이 아니다.
기타 원칙
백엔드는 정답은 존재하지 않는다. 보다 적절한 좋은 방향으로 찾아 나가는 것
'소프트웨어 개발자 > 좋은 API, DB 설계하기' 카테고리의 다른 글
[좋은 API 설계하기] 조회 한 데이터 없음 - 상태코드 200? (0) | 2024.01.31 |
---|---|
[좋은 API 설계하기] 응답 Schema 의 Null 값 처리 (0) | 2024.01.31 |
[좋은 API 설계하기] 한 페이지에 API 몇개? (0) | 2024.01.30 |
[좋은 API 설계하기] Query Parameter (쿼리파라미터) (0) | 2024.01.30 |
[좋은 DB 설계하기] RDB에서 JsonField 사용 vs 관계형 테이블 맺기 (0) | 2023.05.23 |