API
API Introduction
01.software API 개요
API Introduction
01.software는 REST API와 GraphQL API를 모두 제공합니다.
API 엔드포인트
Base URL
Production: https://api.01.software
Development: http://localhost:3000SDK 사용 (권장)
import { createBrowserClient } from '@01.software/sdk'
const client = createBrowserClient({
clientKey: process.env.NEXT_PUBLIC_SOFTWARE_CLIENT_KEY
})SDK를 사용하면 타입 안전성과 자동 완성을 제공받을 수 있습니다.
API 타입
REST API
표준 RESTful API입니다.
| 메서드 | 경로 | 설명 |
|---|---|---|
| GET | /api/{collection} | 목록 조회 |
| GET | /api/{collection}/{id} | 단일 조회 |
| POST | /api/{collection} | 생성 |
| PATCH | /api/{collection}/{id} | 수정 |
| DELETE | /api/{collection}/{id} | 삭제 |
# 목록 조회
GET /api/products?limit=10&where[status][equals]=active
# 단일 항목 조회
GET /api/products/{id}
# 생성
POST /api/products
# 수정
PATCH /api/products/{id}
# 삭제
DELETE /api/products/{id}GraphQL API
강력한 쿼리 언어를 제공합니다.
query {
Products(limit: 10, where: { status: { equals: "active" } }) {
docs {
id
title
price
categories {
name
}
}
totalDocs
hasNextPage
}
}GraphQL Playground
개발 환경에서 GraphQL Playground를 사용할 수 있습니다:
http://localhost:3000/api/graphql-playground인증
Client Key (Public)
브라우저에서 사용 가능한 공개 키입니다.
const client = createBrowserClient({
clientKey: process.env.NEXT_PUBLIC_SOFTWARE_CLIENT_KEY
})Secret Key (Private)
서버에서만 사용하는 비밀 키입니다. JWT 생성에 사용됩니다.
const client = createServerClient({
clientKey: process.env.NEXT_PUBLIC_SOFTWARE_CLIENT_KEY,
secretKey: process.env.SOFTWARE_SECRET_KEY
})Secret Key는 절대 브라우저에 노출하면 안 됩니다!
인증 헤더
# Bearer 토큰 방식
Authorization: Bearer <jwt_token>
# 또는 Cookie 방식 (브라우저)
Cookie: payload-token=<jwt_token>Rate Limiting
API 호출 제한이 적용됩니다.
| Plan | Limit |
|---|---|
| Free | 10,000 calls/month |
| Basic | 100,000 calls/month |
| Pro | 1,000,000 calls/month |
| Enterprise | 무제한 |
Response Headers
X-RateLimit-Limit: 100000
X-RateLimit-Remaining: 99950
X-RateLimit-Reset: 1640995200응답 형식
목록 조회 응답
{
"docs": [...],
"totalDocs": 100,
"limit": 10,
"page": 1,
"totalPages": 10,
"hasNextPage": true,
"hasPrevPage": false,
"pagingCounter": 1
}단일 조회 응답
{
"id": "...",
"title": "...",
"createdAt": "2024-01-01T00:00:00.000Z",
"updatedAt": "2024-01-01T00:00:00.000Z"
}에러 응답
{
"errors": [
{
"message": "Validation failed",
"data": [
{
"field": "email",
"message": "Email is required"
}
]
}
]
}HTTP Status Codes
| Code | Description |
|---|---|
| 200 | Success |
| 201 | Created |
| 400 | Bad Request |
| 401 | Unauthorized |
| 403 | Forbidden |
| 404 | Not Found |
| 429 | Too Many Requests |
| 500 | Internal Server Error |
다음 단계
- REST API - REST API 상세 가이드
- GraphQL - GraphQL API 가이드
- Authentication - 인증 방법
- Rate Limiting - Rate Limiting 상세