ChatGPT API 엔드포인트 설계 프롬프트 - RESTful/GraphQL API

📋 완성된 프롬프트 (복사해서 사용하세요)

당신은 10년 이상의 실무 경력을 보유한 시니어 API 아키텍트입니다. OpenAPI 3.0 표준을 준수하여 확장 가능하고 유지보수가 용이한 API를 설계해 주세요.

According to the 2024 State of API Report, 잘 설계된 API는 개발 생산성을 최대 40% 향상시키며, 83%의 개발자가 API 문서의 품질을 기술 선택의 핵심 기준으로 고려합니다. 이러한 업계 표준을 반영하여 체계적인 API를 설계하세요.

## 서비스 정보
- 서비스명: {{서비스명}} (예: 사용자 관리 API, 주문 처리 시스템)
- 도메인/산업: {{도메인}} (예: 이커머스, 핀테크, SaaS)
- 핵심 기능: {{핵심_기능}} (예: 사용자 CRUD, 로그인, 검색)
- API 아키텍처: {{API_아키텍처}} (REST / GraphQL / gRPC 중 선택)
- 인증 방식: {{인증_방식}} (예: JWT, OAuth2, API Key)

## 비기능 요구사항
- 예상 트래픽 규모: {{예상_트래픽}} (예: 일 10만 요청, 1000 RPS)
- 보안 요구사항: {{보안_요구사항}} (예: GDPR 준수, PCI-DSS, 일반 보안)

## 출력 형식
1. OpenAPI 3.0 스펙 (YAML 형식)
2. 엔드포인트 요약표 (메서드, 경로, 용도, 인증 여부)
3. 요청/응답 예시 (JSON 스키마 포함)
4. 표준 에러 처리 포맷 (에러 코드 체계)
5. 버전 관리 전략 권장사항
```

## 간단 버전

```text
{{서비스명}} 서비스의 API 엔드포인트를 설계하세요.

- 핵심 기능: {{핵심_기능}}
- 인증 방식: {{인증_방식}}
- API 스타일: {{API_아키텍처}}

다음을 포함하여 출력해 주세요: 엔드포인트 목록, 요청/응답 예시, 표준 에러 포맷.
```

---

## 입력값 가이드

| 입력 항목 | 한국어 설명 | placeholder | 예시 |
|------|------|---------|---------|
| **서비스명** | 만들 API의 이름을 입력해주세요 | 예: 사용자 관리 API | `사용자 관리 API`, `주문 처리 시스템`, `결제 게이트웨이` |
| **도메인** | 서비스가 속한 산업 분야를 선택해주세요 | 예: 이커머스 | `이커머스`, `SaaS`, `핀테크`, `헬스케어` |
| **핵심_기능** | API가 제공할 핵심 기능들을 입력해주세요 | 예: 사용자 CRUD, 로그인, 검색 | `사용자 CRUD, 로그인, 검색`, `상품 관리, 주문 처리` |
| **API_아키텍처** | API 설계 방식을 선택해주세요 | REST, GraphQL, gRPC 중 선택 | `REST`, `GraphQL`, `gRPC` |
| **인증_방식** | 사용자 인증 방식을 선택해주세요 | JWT, OAuth2, API Key 중 선택 | `JWT`, `OAuth2`, `API Key`, `Session` |
| **예상_트래픽** | 예상 트래픽 규모를 입력해주세요 | 예: 일 10만 요청 | `일 10만 요청`, `1000 RPS`, `소규모` |
| **보안_요구사항** | 준수해야 할 보안 규정을 선택해주세요 | 예: GDPR, 없음 | `GDPR`, `PCI-DSS`, `ISO 27001`, `없음` |

---

## 인풋 필드

```text
[서비스명]
▼ 선택하거나 직접 입력
placeholder: "예: 사용자 관리 API"
설명: 만들 API의 이름을 입력해주세요

[도메인]
▼ 드롭다운 선택
옵션: 이커머스, SaaS, 핀테크, 헬스케어, 게임, 교육, 기타
placeholder: "예: 이커머스"
설명: 서비스가 속한 산업 분야를 선택해주세요

[핵심_기능]
▼ 텍스트 입력
placeholder: "예: 사용자 CRUD, 로그인, 검색"
설명: API가 제공할 핵심 기능들을 쉼표로 구분해서 입력해주세요

[API_아키텍처]
▼ 라디오 버튼 선택
옵션: ☐ REST  ☐ GraphQL  ☐ gRPC
설명: API 설계 방식을 선택해주세요 (REST가 가장 일반적입니다)

[인증_방식]
▼ 드롭다운 선택
옵션: JWT, OAuth2, API Key, Session, 없음
placeholder: "JWT"
설명: 사용자 인증 방식을 선택해주세요

[예상_트래픽]
▼ 텍스트 입력
placeholder: "예: 일 10만 요청"
설명: 예상되는 트래픽 규모를 입력해주세요 (소규모/중규모/대규모로도 입력 가능)

[보안_요구사항]
▼ 드롭다운 선택
옵션: 없음, GDPR, PCI-DSS, ISO 27001, 기타
placeholder: "없음"
설명: 준수해야 할 보안 규정이 있으면 선택해주세요
```

---

## HTTP 메서드

| 메서드 | 용도 | 멱등성 |
|--------|------|--------|
| **GET** | 리소스 조회 | O |
| **POST** | 리소스 생성 | X |
| **PUT** | 전체 교체 | O |
| **PATCH** | 부분 수정 | X |
| **DELETE** | 삭제 | O |

---

## 상태 코드

| 코드 | 의미 | 사용 시점 |
|------|------|----------|
| **200** | OK | 성공 |
| **201** | Created | 생성 성공 |
| **204** | No Content | 삭제 성공 |
| **400** | Bad Request | 잘못된 요청 |
| **401** | Unauthorized | 인증 필요 |
| **403** | Forbidden | 권한 없음 |
| **404** | Not Found | 리소스 없음 |
| **409** | Conflict | 충돌 |
| **429** | Too Many Requests | 제한 초과 |
| **500** | Internal Error | 서버 오류 |

---

## RESTful 네이밍

```
✅ 좋은 예:
GET  /api/v1/users
GET  /api/v1/users/{id}
POST /api/v1/orders
PATCH /api/v1/orders/{id}

❌ 나쁜 예:
GET /api/v1/getUsers
POST /api/v1/createOrder
```

---

## 응답 포맷

```json
// 성공
{
  "data": { /* 응답 데이터 */ },
  "meta": { "timestamp": "...", "requestId": "..." }
}

// 에러
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "요청 데이터가 유효하지 않습니다."
  }
}

// 페이지네이션
{
  "data": [...],
  "pagination": { "page": 1, "limit": 20, "total": 150 }
}
```

---

## 자주 하는 실수

| 실수 | 해결책 |
|------|--------|
| 동사 사용 | 명사로 변경 (getUsers → users) |
| 잘못된 상태 코드 | HTTP 표준 준수 |
| 과도한 중첩 | 최대 2-3단계로 제한 |
| 문서화 부족 | OpenAPI 스펙 작성 |

---

## 관련 프롬프트

- [데이터베이스-설계](/chatgpt-프롬프트/개발/데이터베이스-설계) - DB 설계
- [시스템-설계](/chatgpt-프롬프트/개발/시스템-설계) - 시스템 아키텍처
- [코드-품질-검토](/chatgpt-프롬프트/개발/코드-품질-검토) - 코드 품질

---

## 자주 묻는 질문 (FAQ)

### Q: REST API와 GraphQL 중 어떤 것을 선택해야 하나요?

**A:** 서비스 특성에 따라 다릅니다:
- **REST**: 표준적이고 캐싱이 중요한 경우, 공개 API에 적합
- **GraphQL**: 유연한 데이터 조회가 필요한 경우, 복잡한 관계형 데이터에 적합
- **gRPC**: 마이크로서비스 간 통신, 높은 성능이 필요한 내부 API에 적합

### Q: API 버전 관리는 어떻게 하나요?

**A:** 세 가지 주요 방식이 있습니다:
1. **URL 경로 방식**: `/api/v1/users` (가장 널리 사용)
2. **헤더 방식**: `Accept: application/vnd.api+json;version=1`
3. **쿼리 파라미터**: `/api/users?version=1`

### Q: JWT와 OAuth2의 차이는 무엇인가요?

**A:**
- **JWT**: 토큰 기반 인증 포맷으로, 상태가 없고 확장성이 좋습니다
- **OAuth2**: 제3자 인가 프레임워크로, 소셜 로그인 등에 사용됩니다
- 실제로는 JWT를 OAuth2의 액세스 토큰으로 함께 사용하는 경우가 많습니다

### Q: 페이지네이션은 어떻게 구현하나요?

**A:**
```json
{
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "totalPages": 8
  }
}