arch-api

What this skill does

## 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.

## 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.

## 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.

## 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`.

## Common Commands/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.

## 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.

## 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`.

## Concrete Usage Examples

1. 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.

2. 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.

## 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).