API 레퍼런스

Base URL: https://api.example.com/v1

인증: 모든 요청에 Authorization: Bearer <token> 헤더가 필요합니다.

응답 형식: Content-Type: application/json

---

공통 응답 형식

성공

{
  "data": { ... },
  "meta": {
    "timestamp": "2026-05-05T00:00:00Z",
    "requestId": "req_abc123"
  }
}

오류

{
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "The requested resource was not found.",
    "details": {}
  }
}

공통 오류 코드

HTTP 코드	코드	설명
400	INVALID_REQUEST	잘못된 요청 형식
401	UNAUTHORIZED	인증 필요
403	FORBIDDEN	권한 없음
404	RESOURCE_NOT_FOUND	리소스 없음
429	RATE_LIMITED	요청 한도 초과
500	INTERNAL_ERROR	서버 오류

---

엔드포인트

아이템 목록 조회

GET /items

쿼리 파라미터

파라미터	타입	필수	기본값	설명
page	integer	아니오	1	페이지 번호
limit	integer	아니오	20	페이지당 항목 수 (최대 100)
q	string	아니오	-	검색 키워드

응답 예시 200 OK

{
  "data": [
    {
      "id": 1,
      "name": "아이템 이름",
      "createdAt": "2026-05-05T00:00:00Z"
    }
  ],
  "meta": {
    "total": 42,
    "page": 1,
    "limit": 20
  }
}

---

아이템 생성

POST /items

요청 바디

{
  "name": "string (필수, 최대 100자)",
  "description": "string (선택)",
  "price": "number (필수, 0 이상)"
}

응답 예시 201 Created

{
  "data": {
    "id": 42,
    "name": "새 아이템",
    "description": null,
    "price": 9900,
    "createdAt": "2026-05-05T00:00:00Z"
  }
}

---

아이템 수정

PUT /items/{id}

경로 파라미터

파라미터	타입	설명
id	integer	아이템 ID

응답 예시 200 OK — 수정된 아이템 객체 반환

---

아이템 삭제

DELETE /items/{id}

응답 204 No Content