01 SOFTWARE
API

REST API

01 SOFTWARE 플랫폼의 REST API 가이드

REST API

01 SOFTWARE는 Payload CMS가 자동 생성하는 RESTful API를 제공합니다.

API 엔드포인트

기본 URL

https://api.01.software/api

개발 환경:

http://localhost:3000/api

인증

Authorization Header

GET /api/products HTTP/1.1
Host: api.01.software
Authorization: Bearer your_jwt_token_here

API Key (Server-side only)

GET /api/products HTTP/1.1
Host: api.01.software
X-API-Key: your_secret_key_here

API Key는 서버 환경에서만 사용하세요. 클라이언트에 노출하지 마세요.

컬렉션 API

모든 컬렉션은 표준 CRUD 엔드포인트를 제공합니다.

List / Search

GET /api/{collection-slug}

Query Parameters

ParameterTypeDescription
limitnumber페이지당 항목 수 (기본: 10)
pagenumber페이지 번호 (기본: 1)
sortstring정렬 필드 (-필드명: 내림차순)
whereobject필터 조건 (JSON)
depthnumber관계 데이터 포함 깊이 (기본: 0)

예제

# 모든 제품 조회
curl "https://api.01.software/api/products" \
  -H "Authorization: Bearer $TOKEN"

# 필터링 및 정렬
curl "https://api.01.software/api/products?\
limit=20&\
page=1&\
sort=-createdAt&\
where[status][equals]=published" \
  -H "Authorization: Bearer $TOKEN"

# 관계 데이터 포함
curl "https://api.01.software/api/posts?depth=2" \
  -H "Authorization: Bearer $TOKEN"

응답

{
  "docs": [
    {
      "id": "product_id",
      "name": "Product Name",
      "price": 10000,
      "status": "published",
      "createdAt": "2026-01-07T10:00:00Z",
      "updatedAt": "2026-01-07T10:00:00Z"
    }
  ],
  "totalDocs": 100,
  "limit": 20,
  "totalPages": 5,
  "page": 1,
  "pagingCounter": 1,
  "hasPrevPage": false,
  "hasNextPage": true,
  "prevPage": null,
  "nextPage": 2
}

Get by ID

GET /api/{collection-slug}/{id}

예제

curl "https://api.01.software/api/products/product_id" \
  -H "Authorization: Bearer $TOKEN"

응답

{
  "id": "product_id",
  "name": "Product Name",
  "price": 10000,
  "status": "published",
  "createdAt": "2026-01-07T10:00:00Z",
  "updatedAt": "2026-01-07T10:00:00Z"
}

Create

POST /api/{collection-slug}

예제

curl -X POST "https://api.01.software/api/products" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "New Product",
    "price": 15000,
    "status": "draft",
    "tenant": "tenant_id"
  }'

응답

{
  "message": "Product created successfully",
  "doc": {
    "id": "new_product_id",
    "name": "New Product",
    "price": 15000,
    "status": "draft",
    "tenant": "tenant_id",
    "createdAt": "2026-01-07T11:00:00Z",
    "updatedAt": "2026-01-07T11:00:00Z"
  }
}

Update

PATCH /api/{collection-slug}/{id}

예제

curl -X PATCH "https://api.01.software/api/products/product_id" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "price": 12000,
    "status": "published"
  }'

응답

{
  "message": "Product updated successfully",
  "doc": {
    "id": "product_id",
    "name": "Product Name",
    "price": 12000,
    "status": "published",
    "updatedAt": "2026-01-07T12:00:00Z"
  }
}

Delete

DELETE /api/{collection-slug}/{id}

예제

curl -X DELETE "https://api.01.software/api/products/product_id" \
  -H "Authorization: Bearer $TOKEN"

응답

{
  "id": "product_id",
  "message": "Product deleted successfully"
}

복잡한 쿼리

Where 조건

Equals

# status가 published인 제품
where[status][equals]=published

Not Equals

# status가 draft가 아닌 제품
where[status][not_equals]=draft

Greater Than / Less Than

# 가격이 10000 이상 50000 이하인 제품
where[price][greater_than_equal]=10000&where[price][less_than_equal]=50000

In / Not In

# 특정 카테고리에 속한 제품
where[category][in]=cat1,cat2,cat3

Like (부분 일치)

# 이름에 "shirt"가 포함된 제품
where[name][like]=shirt

Exists

# thumbnail이 있는 포스트
where[thumbnail][exists]=true

AND / OR 조건

AND 조건

{
  "and": [
    { "status": { "equals": "published" } },
    { "price": { "greater_than": 1000 } }
  ]
}

OR 조건

{
  "or": [
    { "category": { "equals": "electronics" } },
    { "tags": { "contains": "featured" } }
  ]
}

복합 조건

{
  "and": [
    { "status": { "equals": "published" } },
    {
      "or": [
        { "price": { "less_than": 10000 } },
        { "discount": { "greater_than": 0 } }
      ]
    }
  ]
}

파일 업로드

Media 업로드

POST /api/media
Content-Type: multipart/form-data

예제

curl -X POST "https://api.01.software/api/media" \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@/path/to/image.jpg" \
  -F "alt=Image description"

응답

{
  "message": "Media uploaded successfully",
  "doc": {
    "id": "media_id",
    "filename": "image.jpg",
    "mimeType": "image/jpeg",
    "filesize": 102400,
    "width": 1920,
    "height": 1080,
    "url": "https://cdn.01.software/media/image.jpg",
    "createdAt": "2026-01-07T13:00:00Z"
  }
}

인증 엔드포인트

로그인

POST /api/users/login
curl -X POST "https://api.01.software/api/users/login" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "password"
  }'

응답:

{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "user": {
    "id": "user_id",
    "email": "user@example.com",
    "role": "tenant-admin"
  },
  "exp": 1736251200
}

로그아웃

POST /api/users/logout
curl -X POST "https://api.01.software/api/users/logout" \
  -H "Authorization: Bearer $TOKEN"

Me (현재 사용자)

GET /api/users/me
curl "https://api.01.software/api/users/me" \
  -H "Authorization: Bearer $TOKEN"

토큰 갱신

POST /api/users/refresh-token
curl -X POST "https://api.01.software/api/users/refresh-token" \
  -H "Authorization: Bearer $TOKEN"

에러 응답

에러 형식

{
  "errors": [
    {
      "message": "에러 메시지",
      "name": "ValidationError",
      "data": {
        "field": "추가 정보"
      }
    }
  ]
}

일반적인 에러 코드

Status Code설명
400Bad Request - 잘못된 요청
401Unauthorized - 인증 필요
403Forbidden - 권한 없음
404Not Found - 리소스 없음
429Too Many Requests - Rate limit 초과
500Internal Server Error - 서버 오류

SDK 통합

REST API는 SDK를 통해 더 쉽게 사용할 수 있습니다.

import { createBrowserClient } from '@01.software/sdk'

const client = createBrowserClient({
  clientKey: process.env.NEXT_PUBLIC_SOFTWARE_CLIENT_KEY
})

// REST API 자동 호출
const { data } = await client.from('products').find({
  where: { status: { equals: 'published' } },
  limit: 20,
  sort: '-createdAt'
})

다음 단계

API Introduction

01.software API 개요

GraphQL API

01 SOFTWARE 플랫폼의 GraphQL API 가이드

On this page

REST APIAPI 엔드포인트기본 URL인증Authorization HeaderAPI Key (Server-side only)컬렉션 APIList / SearchQuery Parameters예제응답Get by ID예제응답Create예제응답Update예제응답Delete예제응답복잡한 쿼리Where 조건EqualsNot EqualsGreater Than / Less ThanIn / Not InLike (부분 일치)ExistsAND / OR 조건AND 조건OR 조건복합 조건파일 업로드Media 업로드예제응답인증 엔드포인트로그인로그아웃Me (현재 사용자)토큰 갱신에러 응답에러 형식일반적인 에러 코드SDK 통합다음 단계