REST / gRPC API

Argus 透過同一組 proto 定義同時提供三種 API 形態：

形態	用途	程式庫
connectrpc	推薦；HTTP + JSON / proto，server 與瀏覽器都好用	`@connectrpc/connect`
gRPC	內部服務、效能敏感的整合	各語言官方 grpc 程式庫
REST + JSON	簡單工具、curl、Postman	直接 HTTP

完整自動產生的 reference：argus.v1 API Reference（service / RPC / message / enum 全列），來自 proto/gen/grpc-doc/v1/README.md。
OpenAPI 3.1 spec：openapi.yaml（給 Postman / ReDoc / 自動生成 client 用）。

基礎

Base URL

text

<external_url>/v1/...

例：https://argus.corp.example/v1/auditLogs。

認證

bash

# 登入取得 access_token
curl -X POST "$ARGUS/v1/auth/login" \
  -H "Content-Type: application/json" \
  -d '{"loginId":"alice","password":"…"}'

# 後續請求帶 Bearer token
curl -H "Authorization: Bearer $TOKEN" "$ARGUS/v1/issues"

詳見認證模式。Token 有效期由 access_token_duration 設定控制（預設 1h，可在 Settings 調）。

Content type

媒介	header
JSON	`Content-Type: application/json`
proto binary	`Content-Type: application/proto`
connect streaming	`Content-Type: application/connect+json`

錯誤格式

詳見錯誤碼。

服務列表（節錄）

服務	主要 RPC	對應概念
`ActuatorService`	`GetActuatorInfo`	系統健康、版本
`AuthService`	`Login` / `Logout` / `OAuthCallback`	認證
`WorkspaceService`	IAM policy CRUD	IAM
`ProjectService`	Project CRUD + IAM	Plan / Issue / Rollout
`InstanceService`	Instance CRUD + sync	建立第一個 Instance
`DatabaseService`	Database list / transfer / schema	—
`PlanService`	Plan CRUD	Plan
`PlanCheckRunService`	run / get plan check	Plan Check
`IssueService`	Issue CRUD + approve / reject	Issue
`RolloutService`	Rollout + task / taskRun	Rollout
`ReleaseService`	Release CRUD	Release
`RevisionService`	Revision list	Revision
`AuditLogService`	search / export	Audit Log
`SettingService`	workspace setting get / set	Settings
`IdentityProviderService`	IdP CRUD	認證 IdP
`SQLService`	execute / explain / export	SQL Editor

完整列表與每個 RPC 細節：argus.v1 API Reference。

常用操作 cheatsheet

1. 列出我的 issues

bash

curl -s -H "Authorization: Bearer $TOKEN" \
  "$ARGUS/v1/issues?filter=creator:me" | jq '.issues[] | {name, title, status}'

2. 取得 issue 詳情

bash

curl -s -H "Authorization: Bearer $TOKEN" \
  "$ARGUS/v1/projects/play/issues/42" | jq

3. 審批一個 issue

bash

curl -X POST -H "Authorization: Bearer $TOKEN" \
  -d '{"comment":"Approve. Reviewed SQL + plan check."}' \
  "$ARGUS/v1/projects/play/issues/42:approve"

4. 觸發 Rollout 一個 stage

bash

curl -X POST -H "Authorization: Bearer $TOKEN" \
  -d '{"stage":"projects/play/rollouts/100/stages/2"}' \
  "$ARGUS/v1/projects/play/rollouts/100:advance"

5. 查 Audit Log

bash

curl -s -H "Authorization: Bearer $TOKEN" \
  --data-urlencode 'filter=actor:alice AND action:bb.issue.approve' \
  "$ARGUS/v1/auditLogs" | jq

更多範例：查詢 audit log。

6. 讀 / 寫 Workspace Setting

bash

# 讀
curl -s -H "Authorization: Bearer $TOKEN" \
  "$ARGUS/v1/settings/WORKSPACE_PROFILE" | jq

# 寫（require_2fa = true）
curl -X PATCH -H "Authorization: Bearer $TOKEN" \
  -d '{"value":{"workspaceProfile":{"require2fa":true}}}' \
  "$ARGUS/v1/settings/WORKSPACE_PROFILE?updateMask=workspaceProfile.require2fa"

用 OpenAPI 自動生成 client

openapi.yaml 完整描述所有 v1 端點。可以丟給：

工具	用途
Postman / Insomnia	直接 import 後試打
`openapi-typescript-codegen`	生成 TS client
`openapi-generator`	生成 Go / Java / Python / Rust client
ReDoc	自架互動式 API 文件

bash

# 範例：TS client
npx openapi-typescript-codegen \
  --input docs-site/reference/_generated/openapi.yaml \
  --output ./argus-client

connectrpc / gRPC

若用 connectrpc 或 gRPC，直接拿 proto/v1/v1/*.proto 跑 codegen：

bash

# Go
buf generate

# TypeScript（已經由 frontend 自動跑）
# 輸出在 frontend/src/types/proto-es/

範例 connectrpc 呼叫（TS）：

import { createPromiseClient } from "@connectrpc/connect";
import { createConnectTransport } from "@connectrpc/connect-web";
import { IssueService } from "argus-client/v1/issue_service_connect";

const transport = createConnectTransport({ baseUrl: "https://argus.corp.example" });
const client = createPromiseClient(IssueService, transport);

const issue = await client.getIssue({ name: "projects/play/issues/42" });

版本與穩定性

套件	穩定性
`argus.v1.*`	stable；破壞性變更必走 deprecate-then-remove
`argus.store.*`	internal；不對外承諾穩定 — 變更可能任意發生
`argus.internal.v1.*`	公司內部模組（risk-rule、internal-only 介面）— 視同 internal

不要在外部整合中直接讀 argus.store.* payload。它是 JSONB 儲存格式，會跟著 internal refactor 變。

不要做的事

反模式	為什麼
把 `LICENSE_PRIVATE_KEY` / token 寫進 client config	違反 R3；token 走 vault / secret manager
為了快寫 hack，跳 PlanCheck 直接 PATCH plan state	plan state 是 server-side machine，亂改會破壞稽核
用 HTTP basic auth	不支援；只有 Bearer token / cookie session
高頻 poll（< 1s）	大量無效流量；用 streaming RPC 或 watch endpoint

REST / gRPC API ​

基礎 ​

Base URL ​

認證 ​

Content type ​

錯誤格式 ​

服務列表（節錄） ​

常用操作 cheatsheet ​

1. 列出我的 issues ​

2. 取得 issue 詳情 ​

3. 審批一個 issue ​

4. 觸發 Rollout 一個 stage ​

5. 查 Audit Log ​

6. 讀 / 寫 Workspace Setting ​

用 OpenAPI 自動生成 client ​

connectrpc / gRPC ​

版本與穩定性 ​

不要做的事 ​

相關 ​

REST / gRPC API

基礎

Base URL

認證

Content type

錯誤格式

服務列表（節錄）

常用操作 cheatsheet

1. 列出我的 issues

2. 取得 issue 詳情

3. 審批一個 issue

4. 觸發 Rollout 一個 stage

5. 查 Audit Log

6. 讀 / 寫 Workspace Setting

用 OpenAPI 自動生成 client

connectrpc / gRPC

版本與穩定性

不要做的事

相關