arch-api

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Purpose

用途

This skill enables OpenClaw to design, document, and implement API architectures with a focus on REST principles, versioning strategies, HATEOAS, authentication patterns, OpenAPI specifications, and API gateway designs. It ensures APIs are scalable, secure, and standards-compliant.

该技能支持OpenClaw设计、文档化并实现以REST原则、版本控制策略、HATEOAS、认证模式、OpenAPI规范以及API网关设计为核心的API架构，确保API具备可扩展性、安全性并符合标准。

When to Use

使用场景

Use this skill when designing new RESTful APIs, migrating legacy APIs to modern standards, implementing versioning for backward compatibility, or integrating HATEOAS for hypermedia-driven responses. Apply it in microservices environments, when generating OpenAPI docs for Swagger UI, or evaluating auth patterns like JWT for protected endpoints.

在设计新的RESTful API、将遗留API迁移至现代标准、实现版本控制以保障向后兼容性，或集成HATEOAS实现超媒体驱动响应时，可使用该技能。适用于微服务环境、为Swagger UI生成OpenAPI文档，或评估JWT等用于受保护端点的认证模式时。

Key Capabilities

核心能力

REST design: Generates URI structures (e.g., /resources/{id}) and maps HTTP methods (GET, POST) with specific response codes (200 OK, 404 Not Found).
Versioning: Supports URI-based (e.g., /v1/resources) or header-based (e.g., Accept: application/vnd.myapi.v1+json) versioning.
HATEOAS: Adds self-links and related resource links in JSON responses, e.g., {"_links": {"self": "/users/1"}}.
Auth patterns: Implements JWT or OAuth2 flows, including token validation and scopes (e.g., read:users).
OpenAPI docs: Auto-generates OpenAPI 3.0 YAML/JSON specs from code or designs, including schemas and endpoints.
Gateway patterns: Designs API gateways for routing, e.g., using patterns like Kong or AWS API Gateway for load balancing.

REST设计：生成URI结构（例如：/resources/{id}），并将HTTP方法（GET、POST）与特定响应码（200 OK、404 Not Found）进行映射。
版本控制：支持基于URI的版本控制（例如：/v1/resources）或基于请求头的版本控制（例如：Accept: application/vnd.myapi.v1+json）。
HATEOAS：在JSON响应中添加自链接及相关资源链接，示例：{"_links": {"self": "/users/1"}}。
认证模式：实现JWT或OAuth2流程，包括令牌验证和权限范围（例如：read:users）。
OpenAPI文档：从代码或设计自动生成OpenAPI 3.0 YAML/JSON规范，包含数据模型和端点信息。
网关模式：设计用于路由的API网关，例如使用Kong或AWS API Gateway等实现负载均衡的模式。

Usage Patterns

使用模式

Invoke this skill via OpenClaw CLI with the command structure:

openclaw arch-api <subcommand> [flags]

. Always set the auth key via environment variable:

export OPENCLAW_API_KEY=your_api_key

before running commands. For interactive use, pipe outputs to other tools, e.g.,

openclaw arch-api design --rest | jq .

. Use JSON config files for complex inputs, formatted as: {"endpoints": [{"path": "/users", "method": "GET"}]}.

To design a REST API, run:

openclaw arch-api design --type rest --version v1 --hateoas

. For OpenAPI generation, provide a source file:

openclaw arch-api docs --input api-spec.json --output openapi.yaml

通过OpenClaw CLI调用该技能，命令结构为：

openclaw arch-api <subcommand> [flags]

。执行命令前，请务必通过环境变量设置认证密钥：

export OPENCLAW_API_KEY=your_api_key

。如需交互式使用，可将输出管道传输至其他工具，例如：

openclaw arch-api design --rest | jq .

。复杂输入可使用JSON配置文件，格式示例：{"endpoints": [{"path": "/users", "method": "GET"}]}.

设计REST API时，运行：

openclaw arch-api design --type rest --version v1 --hateoas

。生成OpenAPI文档时，提供源文件：

openclaw arch-api docs --input api-spec.json --output openapi.yaml

。

Common Commands/API

常用命令/API

Command:

openclaw arch-api design --rest --endpoints users/get,users/post --version v1

Flags: --hateoas to enable HATEOAS links; --auth jwt for adding JWT auth. Code snippet:

openclaw arch-api design --rest > api_design.json
cat api_design.json | grep "uri"

Command:

openclaw arch-api generate-openapi --from-code ./src/api/controllers.py --output docs/openapi.yaml

Flags: --validate to check for errors; --gateway kong for gateway-specific patterns. Code snippet:

export OPENCLAW_API_KEY=abc123
openclaw arch-api generate-openapi --from-code .

API Endpoint: If using OpenClaw's internal API, POST to /v1/arch-api/design with body: {"type": "rest", "version": "v1"}. Response includes JSON like {"endpoints": [{"path": "/users", "method": "GET"}]}. Config format: Use YAML for inputs, e.g.:
```
endpoints:
  - path: /users
    method: GET
    auth: jwt
```

Command:

openclaw arch-api validate --spec openapi.yaml --check hateoas

Flags: --check versioning to verify version headers.

命令：

openclaw arch-api design --rest --endpoints users/get,users/post --version v1

参数：--hateoas用于启用HATEOAS链接；--auth jwt用于添加JWT认证。代码片段：

openclaw arch-api design --rest > api_design.json
cat api_design.json | grep "uri"

命令：

openclaw arch-api generate-openapi --from-code ./src/api/controllers.py --output docs/openapi.yaml

参数：--validate用于检查错误；--gateway kong用于适配网关特定模式。代码片段：

export OPENCLAW_API_KEY=abc123
openclaw arch-api generate-openapi --from-code .

API端点：若使用OpenClaw内部API，向/v1/arch-api/design发送POST请求，请求体为：{"type": "rest", "version": "v1"}。响应包含类似如下的JSON：{"endpoints": [{"path": "/users", "method": "GET"}]}。配置格式：使用YAML作为输入，示例：
```
endpoints:
  - path: /users
    method: GET
    auth: jwt
```
命令：
```
openclaw arch-api validate --spec openapi.yaml --check hateoas
```
参数：--check versioning用于验证版本请求头。

Integration Notes

集成说明

Integrate this skill with other OpenClaw skills by chaining commands, e.g.,

openclaw chain arch-api se-deployment --input api_design.json

. For external tools, export outputs as files:

openclaw arch-api design > input_for_deployment.txt

. If auth is required, always use the env var pattern:

$OPENCLAW_API_KEY

in scripts, e.g., in a bash script:

#!/bin/bash
export OPENCLAW_API_KEY=your_key
openclaw arch-api design --rest

For config sharing, use JSON files compatible with tools like Swagger Editor, ensuring fields match OpenAPI schemas.

通过链式命令将该技能与其他OpenClaw技能集成，例如：

openclaw chain arch-api se-deployment --input api_design.json

。如需与外部工具集成，可将输出导出为文件：

openclaw arch-api design > input_for_deployment.txt

。若需要认证，脚本中请始终使用环境变量模式：

$OPENCLAW_API_KEY

，例如在bash脚本中：

#!/bin/bash
export OPENCLAW_API_KEY=your_key
openclaw arch-api design --rest

配置文件共享时，使用与Swagger Editor等工具兼容的JSON文件，确保字段匹配OpenAPI规范。

Error Handling

错误处理

Check command exit codes: if

openclaw arch-api design

returns non-zero, parse stderr for messages like "Invalid endpoint format". For API calls, handle HTTP errors: if status == 401, retry with refreshed $OPENCLAW_API_KEY. Use try-catch in scripts:

try {
  openclaw arch-api generate-openapi --input invalid.json
} catch (e) {
  if (e.includes("Validation error")) { console.log("Fix JSON schema"); }
}

Common errors: 400 for malformed inputs (e.g., missing --version flag); 403 if $OPENCLAW_API_KEY is invalid. Log errors with:

openclaw arch-api design 2>> error.log

检查命令退出码：若

openclaw arch-api design

返回非零值，请解析标准错误流获取类似“Invalid endpoint format”（端点格式无效）的提示信息。对于API调用，处理HTTP错误：若状态码为401，请使用刷新后的$OPENCLAW_API_KEY重试。在脚本中使用try-catch语句：

try {
  openclaw arch-api generate-openapi --input invalid.json
} catch (e) {
  if (e.includes("Validation error")) { console.log("Fix JSON schema"); }
}

常见错误：400表示输入格式错误（例如缺少--version参数）；403表示$OPENCLAW_API_KEY无效。使用以下命令记录错误：

openclaw arch-api design 2>> error.log

。

Concrete Usage Examples

实际使用示例

Designing a REST API for a user management system: First, set your auth key:
```
export OPENCLAW_API_KEY=your_key
```
. Then, run:
```
openclaw arch-api design --rest --endpoints users/get,users/post --version v1 --auth jwt --hateoas
```
. This outputs a JSON file with endpoints like {"path": "/users", "method": "GET", "_links": {"self": "/users/1"}}, which you can use to build the API in code.
Generating OpenAPI docs for an existing codebase: Export your key:
```
export OPENCLAW_API_KEY=your_key
```
. Execute:
```
openclaw arch-api generate-openapi --from-code ./src/api --gateway aws --output api_docs.yaml
```
. This creates a YAML file with specs, e.g., including paths for /users and security schemes for JWT, ready for integration with Swagger UI.

为用户管理系统设计REST API：首先设置认证密钥：
```
export OPENCLAW_API_KEY=your_key
```
。然后运行：
```
openclaw arch-api design --rest --endpoints users/get,users/post --version v1 --auth jwt --hateoas
```
。该命令会输出包含类似{"path": "/users", "method": "GET", "_links": {"self": "/users/1"}}的端点信息的JSON文件，可用于代码层面的API开发。
为现有代码库生成OpenAPI文档：导出认证密钥：
```
export OPENCLAW_API_KEY=your_key
```
。执行命令：
```
openclaw arch-api generate-openapi --from-code ./src/api --gateway aws --output api_docs.yaml
```
。该命令会生成一个YAML格式的规范文件，包含/users等路径以及JWT安全方案，可直接集成到Swagger UI中。

Graph Relationships

关联关系

Related to: se-deployment (for deploying designed APIs via gateway patterns).
Connected via: se-architecture cluster (shares tags like "api-design" for collaborative skills).
Links to: se-auth (for detailed auth implementations in APIs).
Associated with: openapi-tool (for extending OpenAPI doc generation).

关联技能：se-deployment（用于通过网关模式部署设计好的API）。
关联集群：se-architecture集群（共享api-design等标签，用于协作技能）。
链接技能：se-auth（用于API中认证逻辑的详细实现）。
关联工具：openapi-tool（用于扩展OpenAPI文档生成功能）。