Api design

Skill furkangonel/cowrangler/bundled_skills/api-design

Autonomous terminal AI agent for workflows and feasible project procedures. Co-Worker Co-Wrangler 🐙

Install

npx -y skills add furkangonel/cowrangler --skill api-design

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

One thing to look at

2 stars2 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 author says it does

Copied from the file, not written here

RESTful API design principles, naming conventions, versioning, and error handling standards

SKILL.md

3.9 KB, as published. Nobody here has run it

API Design SOP

REST Resource Naming

# Use nouns (not verbs) for resources
GET    /users              → list users
POST   /users              → create user
GET    /users/:id          → get specific user
PUT    /users/:id          → replace user (full update)
PATCH  /users/:id          → partial update
DELETE /users/:id          → delete user

# Nested resources (when relationship is strong)
GET    /users/:id/orders   → orders belonging to user
POST   /users/:id/orders   → create order for user

# Actions that don't fit REST (use verb noun)
POST   /users/:id/activate
POST   /payments/:id/refund
POST   /reports/generate

HTTP Status Codes — Use Them Correctly

200 OK              → Successful GET, PUT, PATCH
201 Created         → Successful POST (include Location header)
204 No Content      → Successful DELETE
400 Bad Request     → Invalid input, missing required field
401 Unauthorized    → Not authenticated (no token)
403 Forbidden       → Authenticated but not authorized
404 Not Found       → Resource doesn't exist
409 Conflict        → Duplicate, optimistic lock conflict
422 Unprocessable   → Validation errors (structured errors below)
429 Too Many Req.   → Rate limited (include Retry-After header)
500 Internal Error  → Server fault (never expose stack trace)
503 Unavailable     → Maintenance, overloaded

Request & Response Conventions

Success Response

{
  "data": { ... },
  "meta": {
    "page": 1,
    "per_page": 20,
    "total": 150
  }
}

Error Response (RFC 7807 Problem Details)

{
  "type": "https://api.example.com/errors/validation",
  "title": "Validation Failed",
  "status": 422,
  "detail": "The request body contains invalid data.",
  "errors": [
    { "field": "email", "message": "Invalid email format" },
    { "field": "age", "message": "Must be at least 18" }
  ],
  "trace_id": "abc-123"
}

Versioning Strategy

# URL versioning (most visible, easiest for clients)
/api/v1/users
/api/v2/users

# Header versioning (cleaner URLs)
Accept: application/vnd.api+json; version=2

# Always:
# - Keep v1 alive for at least 6 months after v2 launch
# - Document breaking changes in CHANGELOG
# - Communicate deprecation schedule

Authentication

# Use Bearer tokens in Authorization header
Authorization: Bearer eyJhbGc...

# Never in URL query params (shows in logs!)
❌ GET /api/users?token=secret

# Rate limit all endpoints
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1704067200

Pagination

# Cursor-based (preferred for large datasets)
GET /posts?cursor=eyJpZCI6MTB9&limit=20
→ { data: [...], next_cursor: "eyJpZCI6MzB9" }

# Offset-based (simpler, fine for smaller datasets)
GET /posts?page=2&per_page=20
→ { data: [...], meta: { total: 100, page: 2 } }

Filtering, Sorting, Field Selection

GET /users?status=active&role=admin       # Filtering
GET /posts?sort=-created_at,title         # Sort (- = desc)
GET /users?fields=id,email,name           # Sparse fieldsets
GET /users?search=john                    # Full-text search

Agent Instructions

When designing or reviewing APIs:

Check existing endpoints in the codebase for consistency
Validate resource naming follows noun conventions
Ensure error responses follow the standard format
Confirm authentication is applied to all protected endpoints
Check that status codes match the documented conventions
Verify pagination is implemented for list endpoints

Why/Failure Modes

[TODO: Explain the reasoning behind this skill's approach and common failure modes to avoid.]

Standalone vs Supercharged

[TODO: Describe how this skill works on its own vs when combined with other tools/context.]

Cross-References

[TODO: Link to other relevant skills or documentation.]