agentleFS
Sign inStart free
peopleforresterpeopleforrester/claude-dotfiles/skills/development/api-designer/SKILL.md

api-designer

Skill3 starsChanged 7 months agoMITView on GitHub

API design and documentation assistant for REST and GraphQL APIs. Use when designing new endpoints, reviewing API structure, or creating API documentation. Follows industry best practices for consistent, intuitive API design.

We split this skill into the rules it gives an agent

7 rules. 0 are common, 2 are distinctive, and 5 are very specific to this project.

  • 0

    Common

    Most of the 27 edited versions we read keep these.

  • 2

    Distinctive

    This author's own choices. Worth a look.

  • 5

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Use nouns for resources: /users, /orders, /products

    line 45
  2. Very specific:

    Use plural form: /users not /user

    line 46
  3. Very specific:

    Use kebab-case for multi-word: /order-items

    line 47
  4. Very specific:

    Use path params for identification: /users/:id

    line 48
  5. Very specific:

    Use query params for filtering: /users?status=active

    line 49
  6. Distinctive:

    Keep nesting shallow (max 2 levels).

    line 59
  7. Distinctive:

    Use camelCase for property names

    line 76

“Common” is measured: kept by at least 6 in 10 of the 27 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

API Designer

Design consistent, intuitive, and well-documented APIs.

When to Use

  • Designing new API endpoints
  • Reviewing existing API structure
  • Creating API documentation
  • Planning API versioning strategy
  • Designing error responses

REST API Design Principles

URL Structure

GET    /resources           # List resources
GET    /resources/:id       # Get single resource
POST   /resources           # Create resource
PUT    /resources/:id       # Replace resource
PATCH  /resources/:id       # Update resource partially
DELETE /resources/:id       # Delete resource

Naming Conventions

  • Use nouns for resources: /users, /orders, /products
  • Use plural form: /users not /user
  • Use kebab-case for multi-word: /order-items
  • Use path params for identification: /users/:id
  • Use query params for filtering: /users?status=active

Nested Resources

GET /users/:userId/orders           # User's orders
GET /users/:userId/orders/:orderId  # Specific order
POST /users/:userId/orders          # Create order for user

Keep nesting shallow (max 2 levels).

Request/Response Design

Request Body

{
  "name": "John Doe",
  "email": "john@example.com",
  "preferences": {
    "newsletter": true,
    "theme": "dark"
  }
}
  • Use camelCase for property names
  • Required fields should be documented
  • Include validation constraints

Success Response

{
  "data": {
    "id": "123",
    "name": "John Doe",
    "email": "john@example.com",
    "createdAt": "2026-01-15T10:30:00Z"
  }
}

List Response with Pagination

{
  "data": [
    { "id": "1", "name": "Item 1" },
    { "id": "2", "name": "Item 2" }
  ],
  "meta": {
    "page": 1,
    "perPage": 20,
    "total": 100,
    "totalPages": 5
  },
  "links": {
    "self": "/items?page=1",
    "next": "/items?page=2",
    "last": "/items?page=5"
  }
}

Error Response (RFC 7807)

{
  "type": "https://api.example.com/errors/validation",
  "title": "Validation Error",
  "status": 400,
  "detail": "The request body contains invalid data",
  "instance": "/users/123",
  "errors": [
    {
      "field": "email",
      "message": "Invalid email format"
    }
  ]
}

HTTP Status Codes

Success (2xx)

CodeUse When
200 OKRequest succeeded (GET, PUT, PATCH)
201 CreatedResource created (POST)
204 No ContentSuccess with no body (DELETE)

Client Errors (4xx)

CodeUse When
400 Bad RequestMalformed request / validation error
401 UnauthorizedMissing or invalid authentication
403 ForbiddenAuthenticated but not authorized
404 Not FoundResource doesn't exist
409 ConflictResource conflict (duplicate)
422 UnprocessableValid syntax but semantic error
429 Too Many RequestsRate limit exceeded

Server Errors (5xx)

CodeUse When
500 Internal ErrorUnexpected server error
502 Bad GatewayUpstream service error
503 UnavailableService temporarily unavailable

API Versioning

URL Path (Recommended)

/v1/users
/v2/users

Header-based

Accept: application/vnd.api+json; version=1

Authentication

Bearer Token

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

API Key

X-API-Key: sk_live_abc123...

Documentation Template

## Create User

Creates a new user account.

### Request

`POST /v1/users`

#### Headers

| Header | Required | Description |
|--------|----------|-------------|
| Authorization | Yes | Bearer token |
| Content-Type | Yes | application/json |

#### Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| name | string | Yes | User's full name |
| email | string | Yes | Email address (unique) |

#### Example

\`\`\`json
{
  "name": "John Doe",
  "email": "john@example.com"
}
\`\`\`

### Response

#### 201 Created

\`\`\`json
{
  "data": {
    "id": "usr_123",
    "name": "John Doe",
    "email": "john@example.com",
    "createdAt": "2026-01-15T10:30:00Z"
  }
}
\`\`\`

#### 400 Bad Request

\`\`\`json
{
  "type": "validation_error",
  "title": "Validation Error",
  "status": 400,
  "errors": [
    { "field": "email", "message": "Email already exists" }
  ]
}
\`\`\`

Design Checklist

  • Resource names are nouns, plural
  • HTTP methods used correctly
  • Consistent response format
  • Proper status codes
  • Pagination for lists
  • Versioning strategy defined
  • Authentication documented
  • Error format standardized
  • Rate limiting documented

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

Reviews can't be read right now.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free