[좋은 API 설계하기] 기타

API를 설계하며 고민 한 것들을 적어 놓는 공간.

 

백엔드가 고려해야 될 것 들

• Restful 한 API 설계를 했는지
• 문서화가 좋은지 사용법이 명확한지 (외부 SDK로 배포하더라도 괜찮은 정도의 퀄인지 생각해보기)
• API가 UI에 종속되지 않아야 한다 -> UI가 바뀌더라도, 사용 할수 있는가
• 백엔드의 1차적인 유저는 프론트라는 점
• 아 이사람 api 잘 짜주던데~

 

좋은 API 문서 예시

네이버 NCloud (링크)

• 상태코드를 존중한 Restful 한 작성

 

NHN (링크)

• 모든 API를 200으로 처리함 (링크)
• 성공과 실패에 대한 

 

Redoc 활용 좋은 예시

• Redoc에서 상태코드를 지켜서 문서화 (링크)

 

FE와 배포에 대한 고민

문제 : FE와 BE가 배포 시점이 맞지 않아, 오류가 발생

항상 서로가 같이 배포되어야 하는가?

 

결국에는 V1(이전버전), V2(이후버전) 버전을 앞으로 나아가면서(혹은 자원의 리소스 주소를 바꿔주는 것도 가능) 백엔드가 관리해주는 것이 일반적 (조금이나마 안정적인 측면)

 

단 백엔드가 시간이 지나면, 관리포인트가 거대해지므로 어느 순간 강제로 버전을 deprecated 하여 상위 버전으로 업데이트를 꼭 전제하기

 

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의 차이

1. patch와 put을 나누는 기준은 자원에 대한 일괄 수정을 보장하는지, 부분 수정을 보장하는지에 대한 여부
2. 프론트에서 던지는 payload에 대해 있고 없고의 설명이 아니다.

 

기타 원칙

백엔드는 정답은 존재하지 않는다. 보다 적절한 좋은 방향으로 찾아 나가는 것