3. 빠른 시작(Quick Start)

LOCAL 모드에서는 이미 발급받은 Client ID와 API Key가 필요하다.

IDP 모드에서는 외부 IdP에서 발급한 JWT를 준비한 뒤 2단계부터 진행한다.

Swagger UI 사용

curl 대신 Swagger UI를 사용하면 브라우저에서 API 명세를 확인하고 API를 직접 호출할 수 있다. Access Token 발급, 컬렉션 생성, 문서 삽입 및 조회 등의 작업을 브라우저에서 손쉽게 수행할 수 있다.

Swagger UI 활성화 방법 및 접속 URL은 2.5 Swagger UI 설정을 참고 한다.

다음은 Swagger UI를 사용하지 않고, curl을 이용하여 Access Token 발급부터 컬렉션 생성, 문서 삽입 및 조회까지의 기본 흐름을 순서대로 진행해본다.

1단계: Access Token 발급(LOCAL 모드 전용)

LOCAL 모드에서는 아래의 API를 사용하여 인증에 필요한 Access Token과 Refresh Token을 발급받는다.

curl -X POST http://localhost:8080/api/auth/token \
  -H "Content-Type: application/json" \
  -d '{"clientId": "myClient", "apiKey": "generated_api_key"}'

응답:

{
    "type":"Bearer",
    "token":"eyJhbGciOiJIUzI1NiJ9.....",
    "refreshToken":"eyJhbGciOiJIUzI1NiJ9......",
    "expiresIn":3600000
}

Note

외부 IdP를 사용하는 경우 Access Token 및 Refresh Token은 해당 IdP 서비스로부터 발급받아 사용한다.

2단계: 컬렉션 생성

문서를 저장할 컬렉션을 생성한다.

curl -X POST http://localhost:8080/api/collections \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"name": "books"}'

응답:

{
    "name":"books",
    "keyGeneration":"UUID",
    "keyColumnType":"VARCHAR",
    "jsonColumnType":"JSON"
}

3단계: 문서 삽입

생성한 컬렉션에 문서를 삽입한다.

curl -X POST http://localhost:8080/api/collections/books/documents \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "document": {
      "title": "1984",
      "author": "George Orwell",
      "year": 1949
    }
  }'

응답:

{
    "insertedKey":"7FAACC393CBE4C95BE57879E8925D427",
    "keyType":"String",
    "affectedCount":1
}

4단계: 문서 조회

컬렉션의 모든 문서를 조회하거나, 조건에 해당하는 문서를 조회한다.

전체 목록 조회

curl -X GET http://localhost:8080/api/collections/books/documents \
  -H "Authorization: Bearer ${TOKEN}"

응답:

{
    "documents":[{
        "key":"7FAACC393CBE4C95BE57879E8925D427",
        "keyType":"String",
        "keyFieldName":"_ID",
        "document":{
            "title":"1984",
            "author":"George Orwell",
            "year":1949
        },
        "created":"2026-04-10T07:20:52.326+00:00",
        "createdBy":"userA",
        "lastModified":"2026-04-10T07:20:52.326+00:00",
        "lastModifiedBy":"userA"
    }],
    "totalCount":1,
    "hasMore":false
}

조건부 조회

curl -X POST http://localhost:8080/api/collections/books/documents/search \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {"year": {"$gte": 1940}},
    "sort": {"year": -1},
    "limit": 10
  }'

응답:

{
    "documents":[{
        "key":"DA4FDE47119D46DDB6A6C759040CC6EB",
        "keyType":"String",
        "keyFieldName":"_ID",
        "document":{
            "title":"1984",
            "author":"George Orwell",
            "year":1949
        },
        "created":"2026-04-10T07:20:52.326+00:00",
        "createdBy":"userA",
        "lastModified":"2026-04-10T07:20:52.326+00:00",
        "lastModifiedBy":"userA"
    }],
    "totalCount":1,
    "hasMore":false
}