REST API

행을 조회하고, 추가하고, 수정하고, 지웁니다. 문법은 PostgREST를 따릅니다.

모든 경로는 https://gridie.ai/api/v1 아래에 있습니다.

테이블 목록


GET /api/v1/tables

이 키로 다룰 수 있는 테이블을 컬럼 정보와 함께 돌려줍니다. 클라이언트를 짜기 전에 모양을 확인하는 용도입니다.


{
  "tables": [
    {
      "name": "orders",
      "label": "주문",
      "description": null,
      "rowCount": 128,
      "columns": [
        { "name": "id", "type": "INTEGER", "nullable": false, "primaryKey": true },
        { "name": "customer", "type": "TEXT", "nullable": true, "label": "고객명" }
      ]
    }
  ]
}

name이 요청에 쓰는 이름이고, label은 그리디 화면에 보이는 이름입니다. 목록이 비어 있다면 아직 어떤 테이블도 API에 열지 않은 것입니다.

이 엔드포인트는 그리디가 더한 것이라 응답이 행 배열이 아니라 tables 키를 가진 객체입니다.

행 조회


GET /api/v1/tables/orders

응답은 감싸는 키 없이 행 배열입니다.

쿼리 파라미터

이름	형식	설명
`select`	쉼표 목록	가져올 컬럼. 기본은 전체
`order`	`컬럼.방향`	`created_at.desc`처럼. 쉼표로 여러 개
`limit`	정수	기본 50, 최대 1000
`offset`	정수	건너뛸 행 수
그 밖의 이름	`연산자.값`	컬럼 필터. `status=eq.paid`


curl "https://gridie.ai/api/v1/tables/orders?select=id,customer,total&status=eq.paid&total=gte.10000&order=created_at.desc&limit=20" \
  -H "apikey: $GRIDIE_API_KEY"

없는 컬럼을 적으면 400과 함께 어떤 이름이 틀렸는지 알려 줍니다. 조용히 무시하지 않습니다.

필터 연산자

연산자	뜻	예
`eq`	같다	`status=eq.paid`
`neq`	다르다	`status=neq.draft`
`gt` `gte`	크다, 크거나 같다	`total=gte.10000`
`lt` `lte`	작다, 작거나 같다	`total=lt.500`
`like`	패턴 일치. `*`가 와일드카드	`name=like.김*`
`ilike`	대소문자 무시 패턴 일치	`email=ilike.*@gmail.com`
`is`	null, true, false 판정	`paid_at=is.null`
`in`	목록 중 하나	`status=in.(paid,shipped)`

not.을 앞에 붙이면 뒤따르는 조건을 통째로 뒤집습니다.


status=not.eq.paid
paid_at=not.is.null

여러 파라미터를 함께 보내면 모두 AND로 묶입니다.

정렬


order=created_at.desc
order=priority.asc.nullslast,created_at.desc

방향은 asc와 desc, null 위치는 nullsfirst와 nullslast를 붙입니다.

전체 개수 세기

기본적으로는 개수를 세지 않습니다. 페이지를 나눠 보여주느라 총계가 필요하면 헤더로 요청하세요.


curl "https://gridie.ai/api/v1/tables/orders?limit=20" \
  -H "apikey: $GRIDIE_API_KEY" \
  -H "Prefer: count=exact"

Content-Range 헤더에 담겨 옵니다.


Content-Range: 0-19/128

요청하지 않았다면 총계 자리가 *입니다. 매번 세면 읽기마다 쿼리가 한 번 더 돌아서 그렇습니다.

행 하나만 받기

Accept 헤더로 단일 객체를 요구할 수 있습니다. supabase-js의 .single()이 이렇게 보냅니다.


curl "https://gridie.ai/api/v1/tables/orders?id=eq.1" \
  -H "apikey: $GRIDIE_API_KEY" \
  -H "Accept: application/vnd.pgrst.object+json"

결과가 정확히 한 행이 아니면 406을 돌려줍니다.

행 추가


POST /api/v1/tables/orders

본문에 객체 하나 또는 객체 배열을 담습니다. 감싸는 키는 없습니다.


curl -X POST "https://gridie.ai/api/v1/tables/orders" \
  -H "apikey: $GRIDIE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Prefer: return=representation" \
  -d '[{"customer":"김지훈","total":42000,"status":"paid"}]'

Prefer: return=representation이 있으면 201과 함께 저장된 행이 돌아오고, 없으면 본문 없이 204만 돌아옵니다.

배열로 여러 행을 보낼 때는 모든 행이 같은 컬럼 집합을 가져야 합니다. 행마다 컬럼이 다르면 어느 쪽을 기본값으로 둘지 요청만 봐서는 정해지지 않아서, 400으로 거절합니다.

업서트

Prefer: resolution=merge-duplicates를 붙이면 기본키가 겹칠 때 갈아 끼웁니다. supabase-js의 .upsert()가 이 헤더를 보냅니다.


curl -X POST "https://gridie.ai/api/v1/tables/orders" \
  -H "apikey: $GRIDIE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Prefer: resolution=merge-duplicates,return=representation" \
  -d '[{"id":1,"status":"shipped"}]'

resolution=ignore-duplicates로 바꾸면 겹치는 행을 건드리지 않고 넘어갑니다.

업서트는 테이블에 기본키가 있어야 합니다. 없으면 무엇을 기준으로 겹쳤다고 볼지 정할 수 없어서 400을 돌려줍니다.

행 수정


PATCH /api/v1/tables/orders

본문에는 바꿀 값을 객체 하나로 담고, 어떤 행을 바꿀지는 쿼리 파라미터 필터로 정합니다.


curl -X PATCH "https://gridie.ai/api/v1/tables/orders?id=eq.1" \
  -H "apikey: $GRIDIE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Prefer: return=representation" \
  -d '{"status":"archived"}'

필터가 하나도 없으면 거절합니다. 조건 없는 UPDATE는 테이블 전체를 덮어씁니다. 정말 전부 바꾸려면 항상 참인 조건을 명시적으로 적으세요. 예를 들어 id=gte.0입니다.

행 삭제


DELETE /api/v1/tables/orders


curl -X DELETE "https://gridie.ai/api/v1/tables/orders?status=eq.draft" \
  -H "apikey: $GRIDIE_API_KEY" \
  -H "Prefer: return=representation"

수정과 마찬가지로 필터가 없으면 거절합니다.

쓰기 응답의 행 수

수정과 삭제는 조건에 걸린 행을 모두 처리합니다. 다만 Prefer: return=representation으로 돌려받는 행은 1000개에서 끊깁니다. 그래서 응답의 Content-Range는 총계 자리를 *로 둡니다.


Content-Range: 0-999/*

돌아온 행의 개수를 바뀐 행의 개수로 읽지 마세요. 1000개를 넘겼다면 다릅니다.

요청 헤더 정리

헤더	하는 일
`apikey`	인증. `Authorization: Bearer <키>`도 됩니다
`Prefer: return=representation`	쓰기 결과로 행을 돌려받습니다. 없으면 204
`Prefer: count=exact`	전체 개수를 세어 `Content-Range`에 담습니다
`Prefer: resolution=merge-duplicates`	POST를 업서트로 바꿉니다
`Prefer: resolution=ignore-duplicates`	겹치는 행을 건너뜁니다
`Accept: application/vnd.pgrst.object+json`	행 하나를 객체로 받습니다

Supabase 클라이언트로 붙이는 방법은 Supabase 호환, 실패했을 때 돌아오는 코드는 에러 코드에 있습니다.