/prd-api-templates

PRD API Specification Templates

`/prd` Phase 3에서 선택한 API 유형의 상세 템플릿. REST / GraphQL / gRPC / WebSocket / OpenAPI 템플릿과 로그인 API 예시를 담고 있다. 필요한 유형 섹션만 참고하여 PRD §5.1 API Specification을 작성한다.

---

3.1 REST API 명세 템플릿

### API: [Endpoint Name]

#### `[METHOD] /api/v1/[resource]`

**Description**: [엔드포인트 설명]

**Authentication**: Required / Optional / None

**Headers**:
| Header | Required | Description |
|--------|----------|-------------|
| Authorization | Yes | Bearer {accessToken} |
| Content-Type | Yes | application/json |

**Request Body**:
```json
{
  "field1": "string (required) - 필드 설명",
  "field2": "number (optional) - 필드 설명",
  "field3": {
    "nested": "string (required) - 중첩 필드 설명"
  }
}

**Request Example**:

{
  "email": "user@example.com",
  "password": "securePassword123",
  "rememberMe": true
}

**Response 200 OK**:

{
  "success": true,
  "data": {
    "id": "string - 리소스 ID",
    "createdAt": "string (ISO 8601) - 생성 시간"
  },
  "meta": {
    "timestamp": "string (ISO 8601)"
  }
}

**Response Example**:

{
  "success": true,
  "data": {
    "id": "usr_123456",
    "email": "user@example.com",
    "createdAt": "2024-01-15T09:30:00Z"
  },
  "meta": {
    "timestamp": "2024-01-15T09:30:00Z"
  }
}

**Error Responses**: | Status | Code | Message | Description | |--------|------|---------|-------------| | 400 | INVALID_INPUT | Invalid request body | 요청 본문 유효성 검사 실패 | | 401 | UNAUTHORIZED | Authentication required | 인증 토큰 누락 또는 만료 | | 403 | FORBIDDEN | Access denied | 권한 없음 | | 404 | NOT_FOUND | Resource not found | 리소스 없음 | | 409 | CONFLICT | Resource already exists | 중복 리소스 | | 422 | VALIDATION_ERROR | Validation failed | 비즈니스 규칙 위반 | | 500 | INTERNAL_ERROR | Internal server error | 서버 오류 |

**Error Response Format**:

{
  "success": false,
  "error": {
    "code": "INVALID_INPUT",
    "message": "Invalid request body",
    "details": [
      {
        "field": "email",
        "message": "Invalid email format"
      }
    ]
  },
  "meta": {
    "timestamp": "2024-01-15T09:30:00Z"
  }
}

**Rate Limiting**:

• Limit: 100 requests per minute
• Headers: X-RateLimit-Limit, X-RateLimit-Remaining

---

#### 3.2 GraphQL Schema 템플릿

```graphql
# Schema Definition
type Query {
  """사용자 정보 조회"""
  user(id: ID!): User

  """사용자 목록 조회 (페이지네이션)"""
  users(
    first: Int = 20
    after: String
    filter: UserFilter
  ): UserConnection!
}

type Mutation {
  """회원가입"""
  signUp(input: SignUpInput!): AuthPayload!

  """로그인"""
  signIn(input: SignInInput!): AuthPayload!

  """로그아웃"""
  signOut: Boolean!
}

type Subscription {
  """실시간 알림 구독"""
  onNotification(userId: ID!): Notification!
}

# Types
type User {
  id: ID!
  email: String!
  name: String!
  createdAt: DateTime!
  updatedAt: DateTime!
}

type AuthPayload {
  accessToken: String!
  refreshToken: String!
  user: User!
}

# Inputs
input SignUpInput {
  email: String!
  password: String!
  name: String!
}

input SignInInput {
  email: String!
  password: String!
  rememberMe: Boolean = false
}

# Pagination (Relay Cursor Connection)
type UserConnection {
  edges: [UserEdge!]!
  pageInfo: PageInfo!
  totalCount: Int!
}

type UserEdge {
  cursor: String!
  node: User!
}

type PageInfo {
  hasNextPage: Boolean!
  hasPreviousPage: Boolean!
  startCursor: String
  endCursor: String
}

# Error Handling
type UserError {
  field: String
  message: String!
  code: ErrorCode!
}

enum ErrorCode {
  INVALID_INPUT
  UNAUTHORIZED
  NOT_FOUND
  CONFLICT
  RATE_LIMITED
}

---

3.3 gRPC Proto 정의 템플릿

syntax = "proto3";

package auth.v1;

option go_package = "github.com/example/auth/v1;authv1";

// AuthService 정의
service AuthService {
  // 회원가입
  rpc SignUp(SignUpRequest) returns (SignUpResponse);

  // 로그인
  rpc SignIn(SignInRequest) returns (SignInResponse);

  // 토큰 갱신
  rpc RefreshToken(RefreshTokenRequest) returns (RefreshTokenResponse);

  // 사용자 정보 스트리밍 (서버 스트리밍)
  rpc WatchUser(WatchUserRequest) returns (stream UserEvent);
}

// Request/Response Messages
message SignUpRequest {
  string email = 1;
  string password = 2;
  string name = 3;
}

message SignUpResponse {
  User user = 1;
  AuthTokens tokens = 2;
}

message SignInRequest {
  string email = 1;
  string password = 2;
  bool remember_me = 3;
}

message SignInResponse {
  User user = 1;
  AuthTokens tokens = 2;
}

message RefreshTokenRequest {
  string refresh_token = 1;
}

message RefreshTokenResponse {
  AuthTokens tokens = 1;
}

message WatchUserRequest {
  string user_id = 1;
}

message UserEvent {
  EventType type = 1;
  User user = 2;
  google.protobuf.Timestamp timestamp = 3;

  enum EventType {
    EVENT_TYPE_UNSPECIFIED = 0;
    EVENT_TYPE_UPDATED = 1;
    EVENT_TYPE_DELETED = 2;
  }
}

// Common Types
message User {
  string id = 1;
  string email = 2;
  string name = 3;
  google.protobuf.Timestamp created_at = 4;
  google.protobuf.Timestamp updated_at = 5;
}

message AuthTokens {
  string access_token = 1;
  string refresh_token = 2;
  int64 expires_in = 3;  // seconds
}

// Error Details (Google API Error Model)
import "google/rpc/status.proto";
import "google/rpc/error_details.proto";

// 에러 코드: google.rpc.Code 사용
// INVALID_ARGUMENT (3), UNAUTHENTICATED (16),
// NOT_FOUND (5), ALREADY_EXISTS (6),
// RESOURCE_EXHAUSTED (8) for rate limiting

---

3.4 WebSocket 이벤트 스펙 템플릿

### WebSocket: [Namespace/Feature]

**Endpoint**: `wss://api.example.com/ws/v1/[namespace]`

**Connection Flow**:

Client Server | | |--- WS Upgrade Request --------->| |<-- 101 Switching Protocols -----| | | |--- auth:connect (token) ------->| |<-- auth:connected (session) ----| | | |<-- event:notification ----------| |--- event:ack (eventId) -------->| | | |--- ping ----------------------->| |<-- pong -------------------