Api design

Skill s-hiraoku/synapse-a2a/.agents/skills/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.From its SKILL.md

Install

npx -y skills add s-hiraoku/synapse-a2a --skill api-design

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

2 things to look at

no licenseNo license file was found in the repository. Code published without one is not open source by default, so using it at work is a question for whoever answers licensing questions where you are.
10 stars10 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its file declares

Copied from the file, not written here

The file declares its own license as MIT. That is the author’s claim about this one file, and it is not the same thing as the license GitHub reports for the repository, which is listed with the other numbers below.

SKILL.md

3.6 KB, 856 tokens by cl100k_base, as published. Nobody here has run it

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

Consistency - Same patterns everywhere (naming, error format, pagination)
Discoverability - A developer should guess the right endpoint/flag without reading docs
Backward compatibility - Additions are safe; removals and renames require versioning
Minimal surface - Expose only what consumers need; internal details stay internal
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

Method	Purpose	Idempotent
GET	Read	Yes
POST	Create / action	No
PUT	Full replace	Yes
PATCH	Partial update	Yes
DELETE	Remove	Yes

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

Code	Use
200	Success (with body)
201	Created
204	Success (no body)
400	Client error (validation)
401	Not authenticated
403	Not authorized
404	Not found
409	Conflict (duplicate, state mismatch)
422	Unprocessable (semantically invalid)
500	Server 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.

What ships with it

Read from the repository

Just SKILL.md. No reference files, no scripts.

Gives 0 of the 12 instructions most apis services skills give in 856 tokens

Counted across 448 of the 471 authors here whose files we hold, read 2026-09-06

Use HTTP status codes semanticallyin 25 of 448, across 11 files
Return 201 with a Location header on createin 24 of 448, across 9 files
Name resources plural, lowercase, kebab-casein 23 of 448, across 9 files
Configure rate limiting with limit headersin 22 of 448, across 8 files
Paginate list endpoints with cursor or offsetin 21 of 448, across 10 files
Version APIs in the URL pathin 21 of 448, across 11 files
Validate request input with a schemain 21 of 448, across 7 files
Add pagination to all list endpointsin 18 of 448, across 15 files
Match HTTP method to the operationin 12 of 448, across 6 files
Return 400 or 422 with field-level detailsin 12 of 448, across 2 files
Check ownership before returning resourcesin 12 of 448, across 2 files
Limit query depth and complexityin 12 of 448, across 7 files

Said here and by no other author read

Reserve verbs for non-CRUD actions
Prefer URL prefix versioning
Return self-describing errors with code, message, details
Expose only what consumers need
Version any removal or rename
Cross-check naming, errors, and pagination across endpoints

Grouped from the skills themselves: near-identical wordings counted once, and counted by distinct author, so one author publishing three of these counts once. Length counted with cl100k_base; the agent that loads this file may tokenize it differently.