use-crud-api

NestJS API 프론트엔드 사용 가이드

핵심 원칙

로컬 파일을 읽거나 코드베이스를 탐색하지 말 것. API가 http://localhost:3000에서 실행 중이므로, 필요한 정보는 직접 API를 호출해서 확인한다.

• 데이터 조회/확인 → curl 또는 fetch로 API 직접 호출
• 스키마/필드 확인 → GET /products?limit=1 로 샘플 응답 확인
• 에러 디버깅 → API 응답 메시지 기반으로 판단

# 예: 데이터 확인이 필요할 때
curl "http://localhost:3000/products?limit=1"

---

프레임워크별 클라이언트 예제

프레임워크	클라이언트	레퍼런스 파일
JavaScript/TypeScript	fetch, axios	references/code-examples.md
NodeJS/Express	fetch, axios (상세)	references/nodejs-client.md
Python/FastAPI	httpx (비동기)	references/fastapi-client.md
Python (일반)	requests (동기)	references/fastapi-client.md

---

기본 정보

• Base URL: http://localhost:3000
• 응답 형식: JSON

---

엔드포인트 목록

Method	Path	설명
GET	/products	목록 조회 (필터/정렬/페이지네이션)
GET	/products/count	조건에 맞는 총 개수
GET	/products/:id	단건 조회
POST	/products	단건 생성
POST	/products/many	다건 생성
POST	/products/rpc/:fn	Postgres 함수 호출
PUT	/products/:id	Upsert
PATCH	/products/:id	단건 수정
PATCH	/products	조건 일치 다건 수정
DELETE	/products/:id	단건 삭제
DELETE	/products	조건 일치 다건 삭제

---

필터 연산자

쿼리 파라미터 형식: {연산자}_{필드명}={값}

자세한 연산자 표: See references/filter-operators.md

연산자	예시	설명
eq	eq_name=Laptop	정확히 일치
neq	neq_status=pending	불일치
gt	gt_price=100	초과
gte	gte_price=100	이상
lt	lt_price=500	미만
lte	lte_price=500	이하
like	like_name=Lap	포함 (대소문자 구분)
ilike	ilike_name=lap	포함 (대소문자 무시)
textSearch	textSearch_name=laptop	대소문자 무시 검색
in	in_name=Fan1,Fan2	목록 중 하나
is	is_active=true	true/false/null 체크
or	or=price.lt.100,stock.eq.0	OR 복합 조건
and	and=price.gte.100,stock.gte.50	AND 복합 조건
filter	filter={"status":{"eq":"active"}}	Raw Prisma where

---

페이지네이션 & 정렬

자세한 내용: See references/pagination-sorting.md

GET /products?page=2&perPage=10
GET /products?sortBy=price,createdAt&order=asc,desc

응답 형식:

{
  "data": [...],
  "count": 100,
  "page": 2,
  "perPage": 10
}

---

생성/수정/삭제

생성

POST /products
Content-Type: application/json

{ "name": "Laptop Pro", "price": 1299.99, "stock": 30 }

다건 생성

POST /products/many
[ { "name": "Mouse", "price": 29.99 }, { "name": "Keyboard", "price": 79.99 } ]

수정

PATCH /products/1
{ "price": 999.99 }

Upsert

PUT /products/1
{ "name": "Laptop", "price": 899.99 }

삭제

DELETE /products/1

---

코드 예시 (빠른 레퍼런스)

각 프레임워크별 상세 예제:

• JavaScript/TypeScript (fetch, axios): references/code-examples.md
• NodeJS/Express (fetch, axios, TypeScript): references/nodejs-client.md
• Python/FastAPI (httpx async): references/fastapi-client.md
• Python (requests sync): references/fastapi-client.md

JavaScript/TypeScript (fetch)

// 목록 조회
const { data, count } = await fetch(
  `${BASE_URL}/products?ilike_name=laptop&gte_price=100&page=1&perPage=10&sortBy=price&order=asc`
).then(r => r.json());

// 생성
const created = await fetch(`${BASE_URL}/products`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ name: 'New Product', price: 99.99 }),
}).then(r => r.json());

// 수정
await fetch(`${BASE_URL}/products/1`, {
  method: 'PATCH',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ price: 89.99 }),
});

// 삭제
await fetch(`${BASE_URL}/products/1`, { method: 'DELETE' });

Python (httpx async)

async with CrudApiClient() as client:
    result = await client.list(page=1, per_page=10, ilike_name="laptop", gte_price=100)
    print(result["data"], result["count"])
    await client.create({"name": "New Product", "price": 99.99, "stock": 10})
    await client.update(1, {"price": 89.99})
    await client.delete(1)

---

SQL Dev Endpoint (dev 모드만)

.env에서 MODE=dev로 설정되어 있을 때만 사용 가능.

POST /sql
{ "sql": "SELECT * FROM Product LIMIT 5" }

자세한 내용: See references/sql-endpoint.md

---

에러 응답

코드	상황
200	성공
201	생성 성공
400	잘못된 요청
404	리소스 없음
409	중복 (unique 제약)
500	서버 오류