* 프로그래머스, 타입스크립트로 함께하는 웹 풀 사이클 개발(React, Node.js) 5기 강의 수강 내용을 정리하는 포스팅.

* 원활한 내용 이해를 위해 수업에서 제시된 자료 이외에, 개인적으로 조사한 자료 등을 덧붙이고 있음.

1. API 설계

• 프론트엔드와 백엔드가 데이터를 주고받는 방식과 규칙을 정의하는 작업

• API란? 이전 포스팅 참조.

• 주로 RESTful API 또는 GraphQL API와 같은 방식으로 설계된다.

2. API 설계의 주요 요소

엔드포인트(Endpoint) 정의

• API 요청을 처리할 URL을 정의.

• 예시)

  /users → 사용자 목록 가져오기
  /users → 새로운 사용자 추가
  /users/{id} → 특정 사용자 정보 가져오기

HTTP 메서드

• 각 요청에는 어떤 HTTP 메서드가 사용되는지 정의.

• HTTP 메서드 예시 (자세한 내용은 이전 포스팅 참조)

  GET: 데이터 조회
  POST: 데이터 생성
  PUT: 데이터 수정 (전체 업데이트)
  PATCH: 데이터 일부 수정
  DELETE: 데이터 삭제

• 예시)

  GET /users → 사용자 목록 가져오기
  POST /users → 새로운 사용자 추가
  GET /users/{id} → 특정 사용자 정보 가져오기

요청(Request)와 응답(Response) 형식

• 요청에서 받을 데이터(파라미터, 바디)를 정의.

• 응답 데이터의 구조를 정의.

• 예시)

{
  "id": 1,
  "name": "John Doe",
  "email": "johndoe@example.com"
}

상태 코드(Status Code)

• 요청 결과에 따라 어떤 HTTP 상태 코드를 반환할 것인가?

• 상태 코드 예시 (자세한 내용은 이전 포스팅 참조)

  200: 성공
  201: 리소스 생성 성공
  400: 잘못된 요청
  401: 인증 실패
  404: 리소스 없음
  500: 서버 오류

인증(Authentication) 및 권한(Authorization)

• API가 보안적으로 안전하게 작동하도록, 어떤 인증 및 권한 체계가 포함되어야 하는가?

• 예시)

  토큰 기반 인증 (예: JWT)
  OAuth 또는 API 키 사용

버전 관리

• API의 유지보수와 하위 호환성을 위해 버전을 명시.
• 무언가 변경사항이 있었다면, 어디가 어떻게 변경되었는지 그리고 버전을 나누어 관리하여 서로 다른 설계도가 혼입되지 않도록 해야한다.

문서화

• 개발을 혼자하는게 아닌 이상, 사실 혼자 하더라도 개발자가 빠르게 이해할 수 있도록 API 사용 방법 등을 문서화 해야한다.

3. API 설계 시 유의점

URL 설계는 명확하고 직관적으로

• URL은 리소스를 명확하게 나타내도록 설계.

• REST 인터페이스 일관성의 4대 제약 조건 포스팅 참조.

• 예시)

  /products/{id}/reviews (상품 리뷰)

데이터 응답 구조은 일관되도록

• API마다 서로 다른 형식의 데이터를 주고받는다면 기능마다 데이터를 받아 처리하는 과정이 상이해진다. 효율성이 팍팍 떨어지는 것.

• 예시) 가령 모든 응답에는 결과 메시지와 data 필드를 포함하도록 한다.

{
  "status": "success",
  "data": {...}
}

에러 처리는 확실하게

• 에러가 발생했을 때에는 원인이 무엇인지 파악하기 쉽도록.

• 다만 보안에 문제가 될 에러 핸들링 방식은 지양.

{
  "status": "error",
  "message": "User not found"
}

확장성도 까먹지 말 것

• 위 원칙들을 잘 준수해서 API를 설계한다면, 향후 다른 API가 추가된다고 해도 큰 문제없이 기능을 확장할 수 있다.

• 반대로 위 원칙들을 무시한다면, 추가된 기능이 어디에 포함되는지 모르고 / 데이터 반환 타입이 제각각이라 어떻게 처리해야하는지 파악하는게 힘들고 / 에러가 발생했을 때 원인 파악이 제대로 안된다.