PmaControl — 开发者与 API
快速入门
使用 curl 查询以下公开资源。此只读 API 无需账户、销售表单或 API 密钥。响应采用 JSON 格式。
curl -sS https://www.pmacontrol.com/api/v1/capabilities
curl -sS 'https://www.pmacontrol.com/api/v1/documentation?language=en'
curl -sS https://www.pmacontrol.com/api/v1/permissions
认证与权限
发现资源和公开沙箱仍可匿名访问。要测试经过身份验证的集成,请在 /oauth/register 自助注册机密 OAuth 客户端,再从 /oauth/token 申请 client_credentials 令牌。sandbox.servers.read 和 sandbox.identity.read 权限范围在 OpenAPI 中声明,并在受保护的路由上执行检查。客户端密钥有效期为 24 小时,令牌有效期最长为 600 秒。这些凭证不允许访问客户安装实例,实例访问权限仍由其管理员单独管理。
契约与错误
OpenAPI 契约描述每个操作、参数和响应。API 错误使用 application/problem+json。公开配额为每个客户端 IP 地址每 60 秒 300 次请求。RateLimit-Policy 和 RateLimit 声明策略、剩余配额及重置前秒数;同时提供 RateLimit-Limit、RateLimit-Remaining 和 RateLimit-Reset 兼容字段。收到 HTTP 429 后,请等待 Retry-After 指定的秒数。这些字段遵循 IETF 草案 httpapi-ratelimit-headers-11;不承诺可用性保证。
免费沙箱
无需账户或密钥即可测试 MariaDB / MySQL 合成响应。指标为固定示例,与客户数据库没有连接。此沙箱仅供读取,不模拟生产权限。现有 Pro 试用需要验证邮箱并提供安装 UUID;试用许可证不是 API 密钥。
curl -sS https://www.pmacontrol.com/api/v1/sandbox/servers
PmaControl 官方 CLI
在 macOS 或 Linux 上通过官方 Homebrew tap 安装 CLI。公式使用 Python 3.13,并验证已发布源代码压缩包的 SHA-256。capabilities、permissions、schema、docs 和 sandbox 命令无需账户或密钥即可返回 JSON。软件包及其源代码在本网站公开提供。
brew tap pmacontrol/agent https://www.pmacontrol.com/downloads/homebrew-agent.git
brew install pmacontrol/agent/pmacontrol-agent
pmacontrol-agent --version
pmacontrol-agent capabilities
pmacontrol-agent docs --language fr
pmacontrol-agent sandbox
自助获取沙箱凭证
以下流程无需注册账户或付款即可创建客户端标识与密钥,然后获取仅具有 sandbox.servers.read 权限的令牌。请用返回值替换 CLIENT_ID、CLIENT_SECRET 和 ACCESS_TOKEN。要测试客户端身份,请明确申请 sandbox.identity.read。每个 IP 每小时最多注册五个客户端,整个服务每小时最多注册 120 个;令牌端点每个 IP 每分钟接受 30 个请求。以当前配额标头和 Retry-After 为准。
curl -sS https://www.pmacontrol.com/oauth/register \
-H 'Content-Type: application/json' \
--data '{"grant_types":["client_credentials"],"response_types":[],"scope":"sandbox.servers.read"}'
curl -sS https://www.pmacontrol.com/oauth/token \
--user 'CLIENT_ID:CLIENT_SECRET' \
--data 'grant_type=client_credentials&scope=sandbox.servers.read'
curl -sS https://www.pmacontrol.com/api/v1/sandbox/authorized-servers \
-H 'Authorization: Bearer ACCESS_TOKEN'
API 版本管理与弃用
REST API v1 目前有效,当前契约版本为 1.1.0。兼容的新增功能使用次要版本号;破坏性更改必须使用新的主版本 URL,例如 /api/v2。目前没有计划停用 v1。停用前,我们至少提前 90 天发布带日期的通知和迁移指南,但有记录的安全紧急情况或法律要求除外。
资源弃用时,Deprecation 按 RFC 9745 使用 @Unix_seconds 格式的结构化日期,Sunset 按 RFC 8594 使用 GMT 时区的 HTTP 日期表示停用时间。Sunset 不得早于 Deprecation。HTTP rel=deprecation 链接指向此策略与迁移说明。有效资源提供该链接,不声明虚构的停用日期。