API Design

API Design

Design consistent, well-documented APIs across REST, GraphQL, gRPC, and CLI interfaces.

When to Use

• Designing new API endpoints or commands
• Reviewing existing API contracts for consistency
• Establishing API naming and versioning conventions
• Planning backward-compatible API changes
• Generating API documentation or OpenAPI specs

Principles

1. Consistency - Same patterns everywhere (naming, error format, pagination)
2. Discoverability - A developer should guess the right endpoint/flag without reading docs
3. Backward compatibility - Additions are safe; removals and renames require versioning
4. Minimal surface - Expose only what consumers need; internal details stay internal
5. Self-describing errors - Error responses should tell the caller what went wrong and how to fix it

REST API Checklist

Naming

• Use plural nouns for resources: /users, /tasks
• Use kebab-case for multi-word paths: /user-settings
• Nest for ownership: /users/{id}/tasks
• Use verbs only for actions that don't map to CRUD: /tasks/{id}/approve

HTTP Methods

Response Format

{
  "data": { ... },
  "meta": { "page": 1, "total": 42 }
}

Error format:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Human-readable description",
    "details": [
      { "field": "email", "reason": "required" }
    ]
  }
}

Status Codes

Pagination

Use cursor-based for large datasets, offset-based for simple cases:

GET /tasks?cursor=abc123&limit=20
GET /tasks?page=2&per_page=20

Versioning

• Prefer URL prefix: /v1/tasks, /v2/tasks
• Use header-based only when URL versioning is impractical

CLI API Checklist

Command Structure

<tool> <noun> <verb> [args] [--flags]

Example: synapse send gemini "Review code" --wait

Flag Conventions

• Long form: --output, --verbose
• Short form for common flags: -o, -v
• Boolean flags: --force, --no-color
• Repeatable: --attach file1 --attach file2
• Mutually exclusive groups: --wait | --notify | --silent

Output

• Default: human-readable
• --json: machine-readable JSON
• --quiet / -q: minimal output
• Exit codes: 0 = success, 1 = error, 2 = usage error

Workflow

Step 1: Define Resources / Commands

List the entities and actions the API must support.

Step 2: Map to Endpoints / Subcommands

Apply naming conventions to produce the API surface.

Step 3: Define Request / Response Schemas

Specify required and optional fields, types, and validation rules.

Step 4: Document Error Cases

For each endpoint, list possible error responses and their meaning.

Step 5: Review for Consistency

Cross-check naming, error format, and pagination across all endpoints.