@howmuchhome-web/api

백엔드 API 호출을 위한 타입 안전한 HTTP 클라이언트 패키지입니다. 개요 및 사용법은 API 패키지를, 컨벤션은 API 컨벤션을 참고하세요.

데코레이터

HTTP 메서드

데코레이터	설명
`@GET(path, searchParams?)`	GET 요청
`@POST(path, searchParams?)`	POST 요청
`@PUT(path, searchParams?)`	PUT 요청
`@PATCH(path, searchParams?)`	PATCH 요청
`@DELETE(path, searchParams?)`	DELETE 요청

path는 문자열 또는 (props) => string 함수를 받습니다. searchParams는 (props, pageParam?) => Record<string, unknown> 함수를 받습니다.

동작 제어

데코레이터	설명
`@SkipAuth`	인증 헤더 없이 요청
`@SilentErrorCodeList(codes)`	지정 에러 코드를 Sentry에 전송하지 않음
`@ResponseType('blob')`	응답을 Blob으로 수신 (기본값: `'json'`)

React Query 옵션

데코레이터	설명
`@QueryOptions(options \| fn)`	`useAPIQuery` 기본 옵션 설정
`@MutationOptions(fn)`	`useAPIMutation` 기본 옵션 설정
`@InfiniteQueryOptions(fn)`	`useAPIInfiniteQuery` 기본 옵션 설정

HowmuchhomeAPI

모든 API 모듈의 베이스 클래스입니다.


class MyAPI extends HowmuchhomeAPI {
  @GET(props => `v1/resource/${props.id}`)
  getResource(props: {id: string}): Promise<Response> {
    return this.fetch(props);
  }
}

this.fetch(props)는 데코레이터에 설정된 HTTP 메서드와 경로로 요청을 전송하고 응답을 제네릭 타입으로 반환합니다.

에러 클래스

ApiServerError

모든 API 에러의 베이스 클래스입니다.


class ApiServerError<Map extends ApiServerErrorMap = ApiServerErrorMap>
  extends HowmuchhomeError

프로퍼티

프로퍼티	타입	설명
`statusCode`	`number`	HTTP 상태 코드
`errorCode`	`string`	서버 에러 코드
`path`	`string`	요청 경로
`method`	`string`	HTTP 메서드
`detail`	`unknown`	에러 상세 정보

스태틱 메서드

메서드	설명
`isApiServerError(error)`	`ApiServerError` 타입 가드
`deserializeForServerAction(error)`	서버 액션 에러 역직렬화
`isServerActionError(error)`	서버 액션 에러 여부 확인

인스턴스 메서드

메서드	설명
`isErrorOfType(code)`	특정 에러 코드 타입 가드
`is401Error()`	401 에러 여부
`is403Error()`	403 에러 여부
`is404Error()`	404 에러 여부
`is422Error()`	422 에러 여부
`is502Error()`	502 에러 여부
`serializeForServerAction()`	서버 액션용 직렬화

HTTP 상태별 에러 클래스

클래스	상태 코드
`ApiServer401Error`	401 Unauthorized
`ApiServer403Error`	403 Forbidden
`ApiServer404Error`	404 Not Found
`ApiServer405Error`	405 Method Not Allowed
`ApiServer422Error`	422 Unprocessable Entity
`ApiServer502Error`	502 Bad Gateway
`MissingAccessTokenError`	액세스 토큰 없음

유틸리티

getAPIPath

API 메서드에서 경로를 추출합니다. 테스트나 쿼리 키 생성에 사용합니다.


import {getAPIPath} from '@howmuchhome-web/api';
 
const path = getAPIPath(VoteAPI.getVoteDetail, {voteId: '123'});
// → 'v1/vote/123'