HTTP 메서드 - 🌲 Sonamu

HTTP 메서드는 API의 의도를 명확하게 표현하고 RESTful 원칙을 따르도록 합니다.

HTTP 메서드 개요

GET

데이터 조회안전하고 멱등성

POST

데이터 생성비멱등성

PUT

데이터 수정멱등성

DELETE

데이터 삭제멱등성

GET - 조회

데이터를 조회할 때 사용합니다. 서버 상태를 변경하지 않습니다.

단일 리소스 조회

class UserModel extends BaseModelClass {
  @api({ httpMethod: "GET" })
  async get(id: number): Promise<User> {
    const rdb = this.getPuri("r");
    
    const user = await rdb
      .table("users")
      .where("id", id)
      .first();
    
    if (!user) {
      throw new Error("User not found");
    }
    
    return user;
  }
}

// 호출: GET /api/user/get?id=1

목록 조회

interface UserListParams {
  page?: number;
  pageSize?: number;
  search?: string;
  role?: UserRole;
  sortBy?: "created_at" | "username";
  sortOrder?: "asc" | "desc";
}

class UserModel extends BaseModelClass {
  @api({ httpMethod: "GET" })
  async list(params: UserListParams): Promise<{
    users: User[];
    total: number;
    page: number;
    pageSize: number;
  }> {
    const rdb = this.getPuri("r");
    
    // 기본값 설정
    const page = params.page || 1;
    const pageSize = params.pageSize || 20;
    const sortBy = params.sortBy || "created_at";
    const sortOrder = params.sortOrder || "desc";
    
    // 쿼리 빌드
    let query = rdb.table("users");
    
    // 검색 조건
    if (params.search) {
      query = query.where((qb) => {
        qb.where("username", "like", `%${params.search}%`)
          .orWhere("email", "like", `%${params.search}%`);
      });
    }
    
    // 역할 필터
    if (params.role) {
      query = query.where("role", params.role);
    }
    
    // 정렬
    query = query.orderBy(sortBy, sortOrder);
    
    // 페이지네이션
    const users = await query
      .limit(pageSize)
      .offset((page - 1) * pageSize)
      .select("*");
    
    // 전체 개수
    const [{ count }] = await rdb
      .table("users")
      .count({ count: "*" });
    
    return {
      users,
      total: count,
      page,
      pageSize,
    };
  }
}

// 호출: GET /api/user/list?page=1&pageSize=20&search=john&role=admin&sortBy=username&sortOrder=asc

관계 데이터 조회

class UserModel extends BaseModelClass {
  @api({ httpMethod: "GET" })
  async getWithProfile(id: number): Promise<{
    user: User;
    profile: Profile | null;
    posts: Post[];
  }> {
    const rdb = this.getPuri("r");
    
    // User 조회
    const user = await rdb
      .table("users")
      .where("id", id)
      .first();
    
    if (!user) {
      throw new Error("User not found");
    }
    
    // Profile 조회 (1:1)
    const profile = await rdb
      .table("profiles")
      .where("user_id", id)
      .first();
    
    // Posts 조회 (1:N)
    const posts = await rdb
      .table("posts")
      .where("user_id", id)
      .orderBy("created_at", "desc")
      .select("*");
    
    return {
      user,
      profile: profile || null,
      posts,
    };
  }
}

GET 메서드 특징:

안전함 (Safe): 서버 상태를 변경하지 않음
멱등성 (Idempotent): 같은 요청을 여러 번 해도 결과 동일
캐시 가능 (Cacheable): 브라우저/프록시에서 캐시 가능
파라미터는 URL 쿼리 스트링으로 전달

POST - 생성

새로운 리소스를 생성할 때 사용합니다.

단순 생성

interface CreateUserParams {
  email: string;
  username: string;
  password: string;
  role: UserRole;
}

class UserModel extends BaseModelClass {
  @api({ httpMethod: "POST" })
  @transactional()
  async create(params: CreateUserParams): Promise<{
    userId: number;
  }> {
    const wdb = this.getPuri("w");
    
    // 중복 체크
    const existing = await wdb
      .table("users")
      .where("email", params.email)
      .first();
    
    if (existing) {
      throw new Error("Email already exists");
    }
    
    // User 생성
    const [user] = await wdb
      .table("users")
      .insert({
        email: params.email,
        username: params.username,
        password: params.password, // 실제로는 해시 필요
        role: params.role,
      })
      .returning({ id: "id" });
    
    return { userId: user.id };
  }
}

// 호출: POST /api/user/create
// Body: { "email": "...", "username": "...", "password": "...", "role": "normal" }

복잡한 생성 (관계 데이터 포함)

interface RegisterParams {
  email: string;
  username: string;
  password: string;
  profile: {
    bio: string;
    avatarUrl?: string;
  };
}

class UserModel extends BaseModelClass {
  @api({ httpMethod: "POST" })
  @transactional()
  async register(params: RegisterParams): Promise<{
    userId: number;
    profileId: number;
  }> {
    const wdb = this.getPuri("w");
    
    // User 생성
    const userRef = wdb.ubRegister("users", {
      email: params.email,
      username: params.username,
      password: params.password,
      role: "normal",
    });
    
    // Profile 생성
    wdb.ubRegister("profiles", {
      user_id: userRef,
      bio: params.profile.bio,
      avatar_url: params.profile.avatarUrl || null,
    });
    
    // 저장
    const [userId] = await wdb.ubUpsert("users");
    const [profileId] = await wdb.ubUpsert("profiles");
    
    return { userId, profileId };
  }
}

배치 생성

class UserModel extends BaseModelClass {
  @api({ httpMethod: "POST" })
  @transactional()
  async createBatch(users: CreateUserParams[]): Promise<{
    userIds: number[];
    count: number;
  }> {
    const wdb = this.getPuri("w");
    
    // 모든 User 등록
    users.forEach((user) => {
      wdb.ubRegister("users", {
        email: user.email,
        username: user.username,
        password: user.password,
        role: user.role,
      });
    });
    
    // 일괄 저장
    const userIds = await wdb.ubUpsert("users");
    
    return {
      userIds,
      count: userIds.length,
    };
  }
}

// 호출: POST /api/user/createBatch
// Body: [
//   { "email": "[email protected]", "username": "user1", ... },
//   { "email": "[email protected]", "username": "user2", ... }
// ]

POST 메서드 특징:

비안전함: 서버 상태를 변경함
비멱등성: 같은 요청을 여러 번 하면 리소스가 중복 생성될 수 있음
캐시 불가능
파라미터는 Body로 전달
일반적으로 생성된 리소스의 ID를 반환

PUT - 수정

기존 리소스를 수정할 때 사용합니다.

전체 수정

interface UpdateUserParams {
  email: string;
  username: string;
  role: UserRole;
  bio: string | null;
}

class UserModel extends BaseModelClass {
  @api({ httpMethod: "PUT" })
  @transactional()
  async update(
    id: number,
    params: UpdateUserParams
  ): Promise<void> {
    const wdb = this.getPuri("w");
    
    // User 존재 확인
    const user = await wdb
      .table("users")
      .where("id", id)
      .first();
    
    if (!user) {
      throw new Error("User not found");
    }
    
    // 전체 필드 업데이트
    await wdb
      .table("users")
      .where("id", id)
      .update({
        email: params.email,
        username: params.username,
        role: params.role,
        bio: params.bio,
      });
  }
}

// 호출: PUT /api/user/update?id=1
// Body: { "email": "...", "username": "...", "role": "admin", "bio": "..." }

부분 수정 (PATCH 스타일)

class UserModel extends BaseModelClass {
  @api({ httpMethod: "PUT" })
  @transactional()
  async updatePartial(
    id: number,
    params: Partial<UpdateUserParams>
  ): Promise<void> {
    const wdb = this.getPuri("w");
    
    // User 존재 확인
    const user = await wdb
      .table("users")
      .where("id", id)
      .first();
    
    if (!user) {
      throw new Error("User not found");
    }
    
    // 전달된 필드만 업데이트
    const updateData: any = {};
    
    if (params.email !== undefined) updateData.email = params.email;
    if (params.username !== undefined) updateData.username = params.username;
    if (params.role !== undefined) updateData.role = params.role;
    if (params.bio !== undefined) updateData.bio = params.bio;
    
    if (Object.keys(updateData).length > 0) {
      await wdb
        .table("users")
        .where("id", id)
        .update(updateData);
    }
  }
}

// 호출: PUT /api/user/updatePartial?id=1
// Body: { "bio": "Updated bio" }  // 다른 필드는 변경 안 됨

상태 변경

class OrderModel extends BaseModelClass {
  @api({ httpMethod: "PUT" })
  @transactional()
  async updateStatus(
    orderId: number,
    status: "pending" | "paid" | "shipped" | "delivered" | "cancelled"
  ): Promise<void> {
    const wdb = this.getPuri("w");
    
    const order = await wdb
      .table("orders")
      .where("id", orderId)
      .first();
    
    if (!order) {
      throw new Error("Order not found");
    }
    
    // 상태 전환 검증
    if (!this.isValidStatusTransition(order.status, status)) {
      throw new Error(`Cannot change status from ${order.status} to ${status}`);
    }
    
    await wdb
      .table("orders")
      .where("id", orderId)
      .update({ status });
  }
  
  private isValidStatusTransition(
    from: string,
    to: string
  ): boolean {
    const transitions: Record<string, string[]> = {
      pending: ["paid", "cancelled"],
      paid: ["shipped", "cancelled"],
      shipped: ["delivered"],
      delivered: [],
      cancelled: [],
    };
    
    return transitions[from]?.includes(to) || false;
  }
}

PUT 메서드 특징:

비안전함: 서버 상태를 변경함
멱등성: 같은 요청을 여러 번 해도 결과 동일
일반적으로 리소스 전체를 교체
파라미터는 Body로 전달
성공 시 빈 응답 또는 업데이트된 리소스 반환

DELETE - 삭제

리소스를 삭제할 때 사용합니다.

단일 삭제

class UserModel extends BaseModelClass {
  @api({ httpMethod: "DELETE" })
  @transactional()
  async remove(id: number): Promise<void> {
    const wdb = this.getPuri("w");
    
    // User 존재 확인
    const user = await wdb
      .table("users")
      .where("id", id)
      .first();
    
    if (!user) {
      throw new Error("User not found");
    }
    
    // 삭제
    await wdb
      .table("users")
      .where("id", id)
      .delete();
  }
}

// 호출: DELETE /api/user/remove?id=1

소프트 삭제

class UserModel extends BaseModelClass {
  @api({ httpMethod: "DELETE" })
  @transactional()
  async softDelete(id: number): Promise<void> {
    const wdb = this.getPuri("w");
    
    const user = await wdb
      .table("users")
      .where("id", id)
      .whereNull("deleted_at")
      .first();
    
    if (!user) {
      throw new Error("User not found");
    }
    
    // deleted_at 설정 (실제 삭제 안 함)
    await wdb
      .table("users")
      .where("id", id)
      .update({
        deleted_at: new Date(),
      });
  }
  
  // 소프트 삭제 복구
  @api({ httpMethod: "PUT" })
  @transactional()
  async restore(id: number): Promise<void> {
    const wdb = this.getPuri("w");
    
    const user = await wdb
      .table("users")
      .where("id", id)
      .whereNotNull("deleted_at")
      .first();
    
    if (!user) {
      throw new Error("User not found or not deleted");
    }
    
    await wdb
      .table("users")
      .where("id", id)
      .update({
        deleted_at: null,
      });
  }
}

배치 삭제

class UserModel extends BaseModelClass {
  @api({ httpMethod: "DELETE" })
  @transactional()
  async removeBatch(ids: number[]): Promise<{
    deletedCount: number;
  }> {
    const wdb = this.getPuri("w");
    
    const deletedCount = await wdb
      .table("users")
      .whereIn("id", ids)
      .delete();
    
    return { deletedCount };
  }
}

// 호출: DELETE /api/user/removeBatch
// Body: { "ids": [1, 2, 3] }

DELETE 메서드 특징:

비안전함: 서버 상태를 변경함
멱등성: 이미 삭제된 리소스를 다시 삭제해도 결과 동일
성공 시 일반적으로 빈 응답 (204 No Content)
소프트 삭제 고려 (deleted_at 컬럼 사용)

메서드 선택 가이드

선택 기준

작업	메서드	예시
단일 조회	GET	`/api/user/get?id=1`
목록 조회	GET	`/api/user/list?page=1`
새로 생성	POST	`/api/user/create`
전체 수정	PUT	`/api/user/update?id=1`
부분 수정	PUT	`/api/user/updatePartial?id=1`
삭제	DELETE	`/api/user/remove?id=1`

RESTful 원칙

좋은 예

class UserModel extends BaseModelClass {
  // ✅ GET: 조회
  @api({ httpMethod: "GET" })
  async list(): Promise<User[]> { /* ... */ }
  
  // ✅ POST: 생성
  @api({ httpMethod: "POST" })
  async create(params: CreateUserParams): Promise<{ userId: number }> { /* ... */ }
  
  // ✅ PUT: 수정
  @api({ httpMethod: "PUT" })
  async update(id: number, params: UpdateUserParams): Promise<void> { /* ... */ }
  
  // ✅ DELETE: 삭제
  @api({ httpMethod: "DELETE" })
  async remove(id: number): Promise<void> { /* ... */ }
}

나쁜 예

class UserModel extends BaseModelClass {
  // ❌ GET으로 데이터 변경
  @api({ httpMethod: "GET" })
  async deleteUser(id: number): Promise<void> {
    // GET은 안전해야 함 (상태 변경 X)
  }
  
  // ❌ POST로 조회
  @api({ httpMethod: "POST" })
  async getUser(id: number): Promise<User> {
    // POST는 생성용
  }
  
  // ❌ DELETE로 수정
  @api({ httpMethod: "DELETE" })
  async updateUser(id: number, params: any): Promise<void> {
    // DELETE는 삭제용
  }
}

다음 단계

파라미터

타입 정의 및 검증

반환 타입

응답 타입 정의하기

@api 데코레이터

기본 사용법

에러 처리

API 에러 핸들링

시작하기

핵심 개념

데이터베이스

API 개발

프론트엔드 통합

테스팅

고급 기능

도구 & CLI

설정

API 레퍼런스

문제 해결

자주 묻는 질문

​HTTP 메서드 개요

GET

POST

PUT

DELETE

​GET - 조회

​단일 리소스 조회

​목록 조회

​관계 데이터 조회

​POST - 생성

​단순 생성

​복잡한 생성 (관계 데이터 포함)

​배치 생성

​PUT - 수정

​전체 수정

​부분 수정 (PATCH 스타일)

​상태 변경

​DELETE - 삭제

​단일 삭제

​소프트 삭제

​관련 데이터와 함께 삭제

​배치 삭제

​메서드 선택 가이드

​선택 기준

​RESTful 원칙

​좋은 예

​나쁜 예

​다음 단계