API 설계 및 협업

API 중심 협업 프로세스 설계

단계별 협업 프로세스

단계	주요 활동	산출물	책임자
1. 기획 & 요구사항 정의	기능 요구사항 수집, 주요 사용자 시나리오 정의	기능 명세서, API 요구사항 목록	기획자, PM
2. API 설계	엔드포인트 정의, 요청/응답 구조 설계, 상태코드 규칙 설정	API 스펙 문서 (OpenAPI/Swagger)	백엔드 개발자, 프론트엔드 개발자 공동
3. 디자인 연계	API 데이터 구조 기반 UI/UX 설계	화면 설계서, Mock 데이터	디자이너
4. Mock API & 테스트	Swagger Mock 서버, Postman, MSW 등을 이용한 프론트/백 개발 병행 테스트	Mock API 서버, 테스트 스크립트	프론트엔드, 백엔드
5. 개발 & 통합	실제 API 구현, 프론트엔드 연동, 통합 테스트	기능 동작 시연, 통합 테스트 보고서	프론트/백엔드
6. 배포 & 운영	API 배포, 모니터링 설정	운영 문서, API 변경 로그	백엔드
7. 유지보수	버그 수정, API 개선, 버전 관리	API v2 스펙	프론트/백엔드

OpenAPI/Swagger 기반 To-Do 관리 API 예시

openapi: 3.0.0
info:
  title: To-Do API
  version: 1.0.0
  description: 간단한 To-Do 관리 API
servers:
  - url: https://api.example.com/v1
paths:
  /todos:
    get:
      summary: 모든 To-Do 조회
      responses:
        '200':
          description: 성공
          content:
            application/json:
              example:
                - id: 1
                  title: "공부하기"
                  completed: false
    post:
      summary: 새로운 To-Do 생성
      requestBody:
        required: true
        content:
          application/json:
            example:
              title: "책 읽기"
      responses:
        '201':
          description: 생성 성공
          content:
            application/json:
              example:
                id: 2
                title: "책 읽기"
                completed: false
  /todos/{id}:
    get:
      summary: 특정 To-Do 조회
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: 성공
          content:
            application/json:
              example:
                id: 1
                title: "공부하기"
                completed: false
    put:
      summary: To-Do 수정
      requestBody:
        required: true
        content:
          application/json:
            example:
              title: "운동하기"
              completed: true
      responses:
        '200':
          description: 수정 성공
    delete:
      summary: To-Do 삭제
      responses:
        '204':
          description: 삭제 성공

협업 중심 API 설계 원칙

1. 명확하고 일관된 엔드포인트 네이밍

   • 동사 대신 명사를 사용 (/users, /todos)

2. 표준 HTTP 상태 코드 활용

   • 200 OK, 201 Created, 400 Bad Request, 404 Not Found, 500 Internal Server Error

3. 데이터 구조 표준화

   • 동일한 키 네이밍 규칙 (snake_case vs camelCase)

4. 버전 관리 필수화

   • URL 버전 명시 (/v1/, /v2/)

5. 문서와 Mock API 제공

   • Swagger, Postman Collection, MSW 등 활용

6. 변경 이력 관리

   • API Changelog 운영

7. 오류 응답 형식 통일

{ "error": "Invalid request", "code": 400 }

UX와 API의 연관성 + 사례

사용자 중심 API 설계 원칙

1. 응답 속도 최적화 → 느린 API는 UX 전체를 저하시킴
   2.필요한 데이터만 응답 → 불필요한 필드 제거, 네트워크 비용 절감
2. 일관된 에러 메시지 → 사용자에게 명확한 피드백 제공

사례

• 서비스: 카카오톡 메시지 전송 API
• UX 기여:
  • 빠른 응답 속도(평균 <100ms)로 실시간 채팅 경험 제공
  • 에러 시 명확한 코드(429 TOO MANY REQUESTS)와 재시도 대기 시간 안내 → 사용자가 왜 실패했는지 이해 가능
  • 응답 JSON 구조 일관성 유지 → 프론트엔드에서 예외 처리 코드 간소화