데이터 API

앱 전용 동적 테이블의 스키마 모델과, 외부에서 행을 읽고 쓰는 HTTP 데이터 API

AxHub 앱은 외부 DB를 따로 붙이지 않고 앱 전용 동적 테이블에 데이터를 저장해요. 앱마다 격리된 PostgreSQL 스키마를 받아 테이블·컬럼을 정의하고 행을 CRUD 해요. 이 페이지는 스키마 모델과, 앱 밖에서 호출하는 HTTP 데이터 API를 정리해요. 앱 안에서는 SDK가 더 간단하고(자세히는 SDK로 백엔드 호출), 단계별 사용법은 동적 테이블 가이드를 보세요.

접근 모델

데이터 영역은 두 가지 면으로 나뉘고, 인증이 서로 달라요.

작업	인증
DDL — 테이블·컬럼·권한 만들기·바꾸기	로그인(OAuth) 전용
데이터 — 행 읽기·쓰기	로그인(OAuth) 또는 PAT(`X-Api-Key`)

앱 안 코드 → SDK (로그인한 사용자 자격, 가장 간단)
앱 밖(에이전트·CI·서버-투-서버) → HTTP 데이터 API + PAT

테이블을 만들고 관리하는 일(DDL)은 PAT로는 못 하고 로그인이 필요해요. PAT는 데이터 읽기·쓰기에만 써요.

스키마 모델

테이블은 컬럼 목록으로 정의해요. 컬럼 형식은 이름:타입[:nullable][:default] 이에요.

axhub tables create orders --app demo \
  --column 'title:text' \
  --column 'qty:int' \
  --column 'done:bool:true:false' \
  --execute

쓸 수 있는 컬럼 타입은 8가지예요.

타입	설명
`text`	문자열
`int` · `bigint`	정수
`float`	실수
`bool`	참/거짓
`timestamptz`	시각(타임존 포함)
`uuid`	UUID
`jsonb`	JSON

owner-column — --owner-column <컬럼>으로 행의 소유자를 구분하는 컬럼을 지정해요.
description — 테이블 설명은 최대 1000 bytes(한글 약 333자).
컬럼이 많으면 --schema table.yaml로 스키마 파일을 넘길 수 있어요.

데이터 API 엔드포인트

외부에서 행을 다룰 땐 HTTP로 직접 호출해요. 경로는 /data/{tenant}/{app}/{table} 이고, base는 https://api.axhub.ai 예요.

메서드 · 경로	하는 일
`GET /data/{tenant}/{app}/{table}`	행 목록
`GET …/{table}/_count`	행 개수
`GET …/{table}/{id}`	단건 조회
`POST …/{table}`	행 추가
`PATCH …/{table}/{id}`	행 수정
`DELETE …/{table}/{id}`	행 삭제

const base = `https://api.axhub.ai/data/${tenant}/${app}/orders`;
const headers = { 'X-Api-Key': process.env.AXHUB_API_KEY, 'Content-Type': 'application/json' };

const rows = await fetch(base, { headers }).then((r) => r.json());        // 목록
await fetch(base, {                                                        // 추가
  method: 'POST', headers, body: JSON.stringify({ title: '첫 주문', qty: 2 }),
});

쿼리 파라미터

목록(GET)과 개수(_count)는 다음 쿼리 파라미터로 거르고 정렬해요.

파라미터	설명
`filter`	백엔드 DSL: `col=value` 또는 `col=op.value` (예: `qty=gt.10`)
`select`	가져올 컬럼, 쉼표로 구분
`sort`	정렬 컬럼, 쉼표로 구분. `-` 접두는 내림차순 (예: `-created_at`)
`page` · `per_page`	페이지네이션 (`per_page` 최대 200)

여러 행을 한 번에 넣을 땐 JSONL(한 줄에 JSON 객체 하나)로 보내요. 일괄 추가 요청은 분당 200건으로 제한돼요.

테이블 권한

기본적으로 테이블은 만든 앱만 접근해요. 다른 앱이나 주체에게 읽기/쓰기를 열어주려면 table grant를 발급해요.

axhub tables grants issue --app demo --table orders \
  --principal-type <주체 종류> --principal-id <주체 id> \
  --actions read,write --execute

axhub tables grants list   --app demo --table orders
axhub tables grants revoke --app demo --table orders --grant-id <grant id>

grant는 주체(principal) 와 행위(actions) 로 구성돼요. 누가(principal-type·principal-id) 무엇을(read/write 등) 할 수 있는지 지정해요.

보안·에러

PAT(X-Api-Key)는 비밀값이에요. 코드에 박지 말고 환경변수에 runtime secret으로 두고 서버에서 읽으세요.
DDL은 PAT 불가 — 테이블·컬럼·권한 변경은 로그인(OAuth)으로만 해요.
응답은 JSON이고, 실패는 X-Request-Id로 추적해요. 자동화는 localized 메시지보다 HTTP status + request id를 우선 쓰세요.