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");

    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": "user1@test.com", "username": "user1", ... },
//   { "email": "user2@test.com", "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 에러 핸들링

​HTTP 메서드 개요

GET

POST

PUT

DELETE

​GET - 조회

​단일 리소스 조회

​목록 조회

​관계 데이터 조회

​POST - 생성

​단순 생성

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

​배치 생성

​PUT - 수정

​전체 수정

​부분 수정 (PATCH 스타일)

​상태 변경

​DELETE - 삭제

​단일 삭제

​소프트 삭제

​관련 데이터와 함께 삭제

​배치 삭제

​메서드 선택 가이드

​선택 기준

​RESTful 원칙

​좋은 예

​나쁜 예

​다음 단계

파라미터

반환 타입

@api 데코레이터

에러 처리

HTTP 메서드 개요

GET - 조회

단일 리소스 조회

목록 조회

관계 데이터 조회

POST - 생성

단순 생성

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

배치 생성

PUT - 수정

전체 수정

부분 수정 (PATCH 스타일)

상태 변경

DELETE - 삭제

단일 삭제

소프트 삭제

관련 데이터와 함께 삭제

배치 삭제

메서드 선택 가이드

선택 기준

RESTful 원칙

좋은 예

나쁜 예

다음 단계