본문으로 건너뛰기

API 명세서 템플릿

개요​

이 문서는 [모듈명] 모듈의 API를 정의합니다.

기능 요구사항​

  • 요구사항 1
  • 요구사항 2
  • 요구사항 3

API 명세​

[API 이름]​

요청 (Request)​

  • HTTP 메서드: [GET/POST/PUT/DELETE]
  • 경로: /[리소스명]
  • Headers: 
    {
      "Authorization": "Bearer {token}",
      "Content-Type": "application/json"
    }
  • Query Parameters: 
    {
      "page": "페이지 번호 (기본값: 1)",
      "size": "페이지 크기 (기본값: 10)"
    }
  • Body: 
    {
      "field1": "값1",
      "field2": "값2"
    }

응답 (Response)​

  • 성공 응답 (200 OK):

    {
      "id": "example-id",
      "field1": "값1",
      "field2": "값2"
    }

  • 성공 응답 (컬렉션, 200 OK):

    {
      "items": [
        {
          "id": "item1",
          "field1": "값1",
          "field2": "값2"
        },
        {
          "id": "item2",
          "field1": "값3",
          "field2": "값4"
        }
      ],
      "metadata": {
        "totalCount": 42,
        "currentPage": 1,
        "pageSize": 10,
        "totalPages": 5
      }
    }

  • 실패 응답 (400 Bad Request):

    {
      "code": "ERROR_CODE",
      "message": "에러 메시지",
      "detail": "상세 설명",
      "errors": [
        {
          "field": "field1",
          "message": "유효하지 않은 값"
        }
      ]
    }

상태 코드​

상태 코드설명발생 조건
200성공요청이 정상적으로 처리됨
201생성됨새 리소스가 생성됨
400잘못된 요청요청 파라미터가 유효하지 않음
401인증 필요인증 토큰이 없거나 유효하지 않음
403권한 없음인증은 되었으나 접근 권한이 없음
404찾을 수 없음요청한 리소스가 존재하지 않음
500서버 오류서버 내부 오류 발생

오류 코드 및 메시지 요약​

HTTP 상태 코드오류 코드메시지설명대응 방법
400INVALID_INPUT잘못된 입력값요청 파라미터가 유효하지 않음요청 파라미터 검증
401UNAUTHORIZED인증 필요인증되지 않은 요청토큰 재발급
403FORBIDDEN권한 없음접근 권한이 없음권한 확인

구현 시 고려사항​

  1. 보안:

    • JWT 토큰 검증
    • 입력값 검증
    • GDPR 준수

  2. 성능:

    • 캐시 사용
    • 데이터베이스 쿼리 최적화
    • 응답 시간 1초 이내

  3. 모니터링:

    • 요청/응답 로깅
    • 에러 로깅
    • 성능 메트릭스 수집

API 사용 흐름​

예시 및 코드​

curl 예시​

curl -X POST http://api.example.com/v1/[리소스명] \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"field1": "값1", "field2": "값2"}'

TypeScript 예시​

// API 호출 예시
const response = await api.post('/[리소스명]', {
  field1: '값1',
  field2: '값2'
});

변경 이력​

날짜버전설명작성자
2025-04-050.3API 버전 관리 가이드라인 반영bok@weltcorp.com
2025-03-160.2용어 통일 및 모듈형 모놀리스 반영bok@weltcorp.com
2025-03-150.1최초 작성bok@weltcorp.com