docyrus-api-dev

Docyrus API 開発者向け

@docyrus/api-client（REST クライアント）と @docyrus/signin（React 認証プロバイダー）を使用して Docyrus API と連携します。OAuth2 PKCE で認証し、強力なフィルタリングや集計機能を使ってデータソースをクエリし、REST エンドポイントを利用できます。

認証のクイックスタート

React アプリ — @docyrus/signin を使用

import { DocyrusAuthProvider, useDocyrusAuth, useDocyrusClient, SignInButton } from '@docyrus/signin'

// 1. Wrap root
<DocyrusAuthProvider
  apiUrl={import.meta.env.VITE_API_BASE_URL}
  clientId={import.meta.env.VITE_OAUTH2_CLIENT_ID}
  redirectUri={import.meta.env.VITE_OAUTH2_REDIRECT_URI}
  scopes={['offline_access', 'Read.All', 'DS.ReadWrite.All', 'Users.Read']}
  callbackPath="/auth/callback"
>
  <App />
</DocyrusAuthProvider>

// 2. Use hooks
function App() {
  const { status, signOut } = useDocyrusAuth()
  const client = useDocyrusClient()  // RestApiClient | null

  if (status === 'loading') return <Spinner />
  if (status === 'unauthenticated') return <SignInButton />

  // client is ready — make API calls
  const user = await client!.get('/v1/users/me')
}

React 以外／サーバー — OAuth2Client を直接使用

import { RestApiClient, OAuth2Client, OAuth2TokenManagerAdapter, BrowserOAuth2TokenStorage } from '@docyrus/api-client'

const tokenStorage = new BrowserOAuth2TokenStorage(localStorage)
const oauth2 = new OAuth2Client({
  baseURL: 'https://api.docyrus.com',
  clientId: 'your-client-id',
  redirectUri: 'http://localhost:3000/callback',
  usePKCE: true,
  tokenStorage,
})

// Auth Code flow
const { url } = await oauth2.getAuthorizationUrl({ scope: 'openid offline_access Users.Read' })
window.location.href = url
// After redirect:
const tokens = await oauth2.handleCallback(window.location.href)

// Create API client with auto-refresh
const client = new RestApiClient({
  baseURL: 'https://api.docyrus.com',
  tokenManager: new OAuth2TokenManagerAdapter(tokenStorage, async () => {
    return (await oauth2.refreshAccessToken()).accessToken
  }),
})

API エンドポイント

データソース項目（テナントごとに異なります）

GET    /v1/apps/{appSlug}/data-sources/{slug}/items          — List with query payload
GET    /v1/apps/{appSlug}/data-sources/{slug}/items/{id}     — Get one
POST   /v1/apps/{appSlug}/data-sources/{slug}/items          — Create
PATCH  /v1/apps/{appSlug}/data-sources/{slug}/items/{id}     — Update
DELETE /v1/apps/{appSlug}/data-sources/{slug}/items/{id}     — Delete one
DELETE /v1/apps/{appSlug}/data-sources/{slug}/items          — Delete many (body: { recordIds })

エンドポイントは、テナントでデータソースが定義されている場合にのみ存在します。テナントの OpenAPI 仕様は GET /v1/api/openapi.json で確認してください。

システムエンドポイント（常に利用可能）

GET    /v1/users          — List users
POST   /v1/users          — Create user
GET    /v1/users/me       — Current user profile
PATCH  /v1/users/me       — Update current user

コネクターの検出と外部リクエストのエンドポイント

GET    /v1/connectors?q=&limit=&offset=                                    — List connectors with keyword search
GET    /v1/connectors/{dataProviderSlug}                                    — Get connector detail (dataSources + actions)
GET    /v1/connectors/{dataProviderSlug}/actions/{actionKey}                — Get action detail (input/output schemas, API endpoint)
GET    /v1/connectors/{dataProviderSlug}/connections                        — Get tenant connections + user connection status
PUT    /v1/connectors/{dataProviderSlug}                                    — Send HTTP request through connector provider auth

スコープ：Read.All、ReadWrite.All、または Connectors.Read.All。PUT エンドポイントには ReadWrite.All が必要です。

コネクター経由でリクエストを送信するための PUT リクエストボディ：

{
  "endpoint": "relative/path/or/absolute-url",
  "requestMethod": "GET",
  "data": { "fields": "id,name", "limit": 20 },
  "contentType": "application/json",
  "headers": { "Authorization": "Bearer <override-token>" },
  "connectionId": "optional-tenant-connection-uuid",
  "connectionAccountId": "optional-connection-account-uuid"
}

コネクターは、プロバイダー設定と保存済みの接続から認証情報（OAuth トークン、ベース URL）を解決します。カスタムの headers.Authorization は、保存済みのトークンを上書きします。

アクション実行エンドポイント

GET    /v1/apps/base/actions                                               — List base actions
GET    /v1/apps/{appSlug}/actions/{actionSlug}                             — Get action metadata
POST   /v1/apps/{appSlug}/actions/{actionSlug}/run                         — Run action directly

アクションの実行では、任意の JSON ボディを入力として受け付けます。省略可能なヘッダー：x-connection-id、x-connection-account-id。

ACL／ロール管理エンドポイント

GET    /v1/users/acl?dataSourceId={uuid}&recordId={uuid}   — Read record ACL rows
POST   /v1/users/acl/share                                 — Upsert record shares
DELETE /v1/users/acl/share                                 — Revoke record shares
PUT    /v1/users/acl/owner                                 — Transfer record ownership

GET    /v1/users/acl/roles                                 — List roles
GET    /v1/users/acl/roles/{roleId}                        — Get one role
POST   /v1/users/acl/roles                                 — Create role
PATCH  /v1/users/acl/roles/{roleId}                        — Update role
DELETE /v1/users/acl/roles/{roleId}                        — Delete role

GET    /v1/users/acl/user-roles                            — List user-role assignments
GET    /v1/users/acl/users/{userId}/roles                  — List one user's roles
POST   /v1/users/acl/users/{userId}/roles                  — Add roles to a user
PUT    /v1/users/acl/users/{userId}/roles                  — Replace a user's full role set
DELETE /v1/users/acl/users/{userId}/roles/{roleId}         — Remove one role assignment

GET    /v1/users/acl/role-queries                          — List role queries
GET    /v1/users/acl/role-queries/{roleQueryId}            — Get one role query
POST   /v1/users/acl/role-queries                          — Create role query
PATCH  /v1/users/acl/role-queries/{roleQueryId}            — Update role query
DELETE /v1/users/acl/role-queries/{roleQueryId}            — Delete role query

ACL ルートでは通常の認証済み API セッションが必要ですが、バックエンドが現在これらを公開ドキュメントから除外しているため、生成された Swagger／OpenAPI 出力に表示されない場合があります。レコード共有、ロールの CRUD、ユーザーへのロール割り当ての管理、またはロールクエリの管理が必要な場合は、RestApiClient を直接呼び出して連携してください。

すべての ACL ロール操作では、API が返すロールの uid 値を使用してください。ネストされたロールオブジェクトには id と uid の両方が含まれ、どちらもロールの UID 値に対応します。

ACL の設定（ロールの作成、操作レベルの権限の割り当て、ロールクエリと組織階層の構築）には、docyrus-acl-design スキル（docyrus acl …）を使用してください。上記のエンドポイントは、アプリ／フロントエンド連携のための実行時 REST インターフェースです。

API 呼び出し

// List items with query payload
const items = await client.get('/v1/apps/base/data-sources/project/items', {
  columns: 'name, status, record_owner(firstname,lastname)',
  filters: { rules: [{ field: 'status', operator: '!=', value: 'archived' }] },
  orderBy: 'created_on DESC',
  limit: 50,
})

// Get single item
const item = await client.get('/v1/apps/base/data-sources/project/items/uuid-here', {
  columns: 'name, description, status',
})

// Create
const newItem = await client.post('/v1/apps/base/data-sources/project/items', {
  name: 'New Project',
  status: 'status-enum-id',
})

// Update
await client.patch('/v1/apps/base/data-sources/project/items/uuid-here', {
  name: 'Updated Name',
})

// Delete
await client.delete('/v1/apps/base/data-sources/project/items/uuid-here')

クエリペイロードの概要

GET items エンドポイントでは、強力なクエリペイロードを受け付けます。

機能	目的
columns	フィールドの選択、リレーションの展開 field(subfields)、別名の指定 alias:field、スプレッド ...field()
filters	50 種類以上の演算子（比較、日付ショートカット、ユーザー関連）を使ったネストされた AND／OR グループ
filterKeyword	検索可能なすべてのフィールドを対象とした全文検索
orderBy	関連フィールドを含むフィールドでの、方向を指定した並べ替え
limit/offset	ページネーション（デフォルトの limit：100）
fullCount	結果とともに一致する総件数を返す
calculations	グループ化に対応した集計：count、sum、avg、min、max
formulas	計算される仮想列（単純な関数、ブロック AST、相関サブクエリ）
childQueries	関連する子レコードをネストされた JSON 配列として取得
pivot	日付範囲の系列に対応したクロス集計マトリックスクエリ
expand	リレーション／ユーザー／列挙型フィールドについて、ID の代わりに完全なオブジェクトを返す

クエリと数式の詳細なリファレンスについては、以下を参照してください：

• references/data-source-query-guide.md
• references/formula-design-guide-llm.md

重要なルール

1. list/get 呼び出しでは、必ず columns を送信してください。指定しない場合、id のみが返されます。
2. データソースのエンドポイントは動的です。テナントで定義されているデータソースに対してのみ存在します。
3. count の計算には id フィールドを使用してください。sum、avg、min、max には実際のフィールドスラッグを使用してください。
4. 子クエリのキーは columns に含める必要があります。childQuery のキーが orders の場合、orders を columns に含めてください。
5. 数式のキーは columns に含める必要があります。数式のキーが total の場合、total を columns に含めてください。
6. 関連フィールドで絞り込む場合は、rel_{{relation_field}}/{{field}} の構文を使用してください。
7. ACL のルートは、生成された OpenAPI から隠れている場合があります。生成されたコレクションのサポートを期待するのではなく、RestApiClient を使って直接呼び出してください。
8. ACL のロール書き込み、ユーザーロールの roleIds、およびロールクエリの roleIds には、ロールの uid 値を優先して使用してください。
9. PUT /v1/users/acl/users/:userId/roles は全置換、POST /v1/users/acl/users/:userId/roles は追加として扱ってください。
10. ロールクエリの query は生の JSON として送信し、該当する場合はバックエンドが dataSourceId から tenantAppId を導出するようにしてください。
11. ロールを削除した後は、依存する ACL の状態を更新してください。ロール一覧、ユーザーロール一覧、ロールクエリ一覧、およびプライマリロールのラベルを表示している UI が対象です。

参考資料

詳しい情報が必要な場合は、以下のファイルを参照してください。

• references/api-client.md — RestApiClient の全 API、OAuth2Client（PKCE、クライアントクレデンシャル、デバイスコードの全フロー）、トークンマネージャー、インターセプター、エラークラス、SSE／ストリーミング、ファイルのアップロード／ダウンロード、HTML から PDF への変換、再試行ロジック
• references/authentication.md — @docyrus/signin の React プロバイダー、useDocyrusAuth/useDocyrusClient フック、hasRole/hasPermission 認可ヘルパー、SignInButton、スタンドアロン認証と iframe 認証のモード、環境変数、API クライアントへのアクセスパターン
• references/data-source-query-guide.md — 最新のクエリペイロードガイド：columns、filters、orderBy、ページネーション、計算、数式、子クエリ、ピボット、演算子のリファレンス
• references/formula-design-guide-llm.md — formulas ペイロードの作成と検証に関する最新の数式設計ガイド