skillZs
★ LIVE SKILL TAGS ★
>>> LIVE SKILLS INDEX <<<
* OPEN SOURCE *
NO LOGIN, NO TRACKING
※ REAL INSTALL DATA ※
← back to all skills
s-hiraoku/synapse-a2a71 installs

api-design

Guide API design for REST, GraphQL, gRPC, and CLI interfaces. Use this skill when designing new APIs, reviewing existing API contracts, or establishing API conventions for a project. Produces consistent, well-documented API specifications.

How do I install this agent skill?

npx skills add https://github.com/s-hiraoku/synapse-a2a --skill api-design
view source ↗

Is this agent skill safe to install?

  • Gen Agent Trust Hubpass

    This skill provides architectural guidance and checklists for designing REST, GraphQL, gRPC, and CLI interfaces. It is purely informational and contains no executable code, remote dependencies, or security risks.

  • Socketpass

    No alerts

  • Snykpass

    Risk: LOW · No issues

  • Runlayerpass

    1 file scanned · No issues

What does this agent skill do?

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

MethodPurposeIdempotent
GETReadYes
POSTCreate / actionNo
PUTFull replaceYes
PATCHPartial updateYes
DELETERemoveYes

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

CodeUse
200Success (with body)
201Created
204Success (no body)
400Client error (validation)
401Not authenticated
403Not authorized
404Not found
409Conflict (duplicate, state mismatch)
422Unprocessable (semantically invalid)
500Server error

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.

Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.

<a href="https://skillzs.dev/skills/s-hiraoku/synapse-a2a/api-design">View api-design on skillZs</a>