Skip to main content
skill CX Codex

api-design · travisjneuman — Claude Code skill: what it does, how to install

api-design is a Claude Code skill with guidelines and templates for REST, gRPC, and tRPC APIs; it helps generate OpenAPI schemas and keep route naming consistent.

MIT 170 installs ★ 114 updated 2026-10-25

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add travisjneuman/.claude --skill api-design -a claude-code
Open on GitHub

What api-design does

This skill supplies the agent with standard conventions for modern API design. It outlines plural noun path naming, explicit HTTP method semantics, status code handling, and structured JSON envelopes for payloads and validation errors. Cursor pagination and URL versioning patterns are also covered.

Beyond basic REST endpoints, the reference includes OpenAPI 3.0 snippets with JWT bearer security schemes and rate-limiting headers. It also includes protocol buffer definitions for gRPC streaming and typed tRPC procedures with Zod validation.

Without a structured error and status code pattern, client integrations waste effort handling edge cases; this guide enforces predictable responses upfront.

What it helps with

  • Design clean REST resource hierarchies without verb-based paths
  • Draft OpenAPI 3.0 specifications with request schemas and bearer auth
  • Implement cursor-based pagination and standard collection envelopes
  • Define gRPC protobuf contracts for streaming and internal services

Example prompts for the agent

  • Design a REST API for user subscriptions and generate the OpenAPI 3.0 schema
  • Review my payment routes against REST conventions and HTTP status code standards
  • Create a Protobuf service definition with cursor pagination for listing audit logs

How to install api-design

1Skills CLI (Vercel)

npx skills add travisjneuman/.claude --skill api-design -a claude-code

2Manually: put the files in place

~/.claude/skills/api-design/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/api-design/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about api-design

How to install api-design in Claude Code?

Run npx skills add travisjneuman/.claude --skill api-design -a claude-code or save the skill directly to ~/.claude/skills/api-design/SKILL.md.

What does the api-design skill do?

It guides code generation towards established API patterns, covering resource naming, status codes, OpenAPI schemas, rate limiting, and gRPC definitions.

Does it support RPC protocols?

Yes, it contains Proto3 definitions for gRPC services alongside full TypeScript router examples for tRPC.

Source text

SKILL.md · MIT
---
name: api-design
description: REST and GraphQL API design best practices including OpenAPI specs. Use when designing APIs, documenting endpoints, or reviewing API architecture.
---

# API Design Guide

Best practices for designing developer-friendly, maintainable APIs.

## REST API Principles

### Resource Naming

**Use nouns, not verbs**:

```
✓ GET /users
✓ GET /users/123
✓ GET /users/123/orders

✗ GET /getUsers
✗ GET /fetchUserById
✗ POST /createNewOrder
```

**Use plural nouns**:

```
✓ /users
✓ /orders
✓ /products

✗ /user
✗ /order
```

**Hierarchical relationships**:

```
/users/{userId}/orders           # User's orders
/users/{userId}/orders/{orderId} # Specific order
```

---

### HTTP Methods

| Method | Purpose                   | Idempotent | Request Body |
| ------ | ------------------------- | ---------- | ------------ |
| GET    | Retrieve resource(s)      | Yes        | No           |
| POST   | Create resource           | No         | Yes          |
| PUT    | Replace resource entirely | Yes        | Yes          |
| PATCH  | Update resource partially | No         | Yes          |
| DELETE | Remove resource           | Yes        | No           |

---

### Status Codes

**Success (2xx)**:

- `200 OK` - Request succeeded
- `201 Created` - Resource created (return Location header)
- `204 No Content` - Success with no response body

**Client Error (4xx)**:

- `400 Bad Request` - Malformed request
- `401 Unauthorized` - Authentication required
- `403 Forbidden` - No permission
- `404 Not Found` - Resource doesn't exist
- `409 Conflict` - State conflict
- `422 Unprocessable Entity` - Validation failed
- `429 Too Many Requests` - Rate limited

**Server Error (5xx)**:

- `500 Internal Server Error` - Unexpected error
- `503 Service Unavailable` - Temporary outage

---

### Response Format

**Successful response**:

```json
{
  "data": {
    "id": "123",
    "name": "John Doe",
    "email": "[email protected]"
  }
}
```

**Collection response**:

```json
{
  "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",
    "prev": null
  }
}
```

**Error response**:

```json
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed",
    "details": [
      {
        "field": "email",
        "code": "INVALID_FORMAT",
        "message": "Must be a valid email address"
      }
    ]
  }
}
```

---

### Pagination

**Offset-based** (simple, but slow on large datasets):

```
GET /users?page=2&perPage=20
GET /users?offset=40&limit=20
```

**Cursor-based** (efficient, recommended):

```
GET /users?cursor=eyJpZCI6MTIzfQ&limit=20
```

Response includes next cursor:

```json
{
  "data": [...],
  "meta": {
    "nextCursor": "eyJpZCI6MTQzfQ",
    "hasMore": true
  }
}
```

---

### Filtering, Sorting, Fields

**Filtering**:

```
GET /users?status=active
GET /users?created_after=2024-01-01
GET /users?role=admin,moderator
```

**Sorting**:

```
GET /users?sort=name
GET /users?sort=-created_at         # Descending
GET /users?sort=status,-created_at  # Multiple fields
```

**Field selection**:

```
GET /users?fields=id,name,email
GET /users?include=orders,profile
```

---

### Versioning

**URL path** (recommended):

```
/api/v1/users
/api/v2/users
```

**Header**:

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

---

## OpenAPI Specification

```yaml
openapi: 3.0.3
info:
  title: My API
  version: 1.0.0
  description: API for managing users

servers:
  - url: https://api.example.com/v1

paths:
  /users:
    get:
      summary: List users
      tags: [Users]
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
      responses:
        "200":
          description: List of users
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/User"

components:
  schemas:
    User:
      type: object
      required: [id, email]
      properties:
        id:
          type: string
        email:
          type: string
          format: email
        name:
          type: string
```

---

## Authentication

**API Keys** (simple, for server-to-server):

```
Authorization: Api-Key YOUR_API_KEY
```

**Bearer Tokens** (JWT, OAuth):

```
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
```

**Include in OpenAPI**:

```yaml
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

security:
  - bearerAuth: []
```

---

## Rate Limiting

Include headers in responses:

```
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640995200
```

Return `429 Too Many Requests` when exceeded.

---

## Security Checklist

- [ ] HTTPS only
- [ ] Authentication on protected routes
- [ ] Input validation
- [ ] Output encoding
- [ ] Rate limiting
- [ ] CORS configuration
- [ ] No sensitive data in URLs
- [ ] Audit logging

---

## gRPC and Protocol Buffers

### Proto Definition

```protobuf
syntax = "proto3";
package user.v1;

service UserService {
  rpc GetUser(GetUserRequest) returns (User);
  rpc ListUsers(ListUsersRequest) returns (ListUsersResponse);
  rpc CreateUser(CreateUserRequest) returns (User);
  rpc StreamUpdates(StreamRequest) returns (stream UserUpdate);
}

message User {
  string id = 1;
  string name = 2;
  string email = 3;
  google.protobuf.Timestamp created_at = 4;
}

message GetUserRequest {
  string id = 1;
}

message ListUsersRequest {
  int32 page_size = 1;
  string page_token = 2;
}

message ListUsersResponse {
  repeated User users = 1;
  string next_page_token = 2;
}
```

### When to Use gRPC vs REST

| Factor            | gRPC                        | REST                        |
| ----------------- | --------------------------- | --------------------------- |
| **Performance**   | Binary, fast                | JSON, human-readable        |
| **Streaming**     | Bidirectional               | SSE/WebSocket workaround    |
| **Type safety**   | Proto generates types       | OpenAPI + codegen           |
| **Browser**       | Needs gRPC-Web proxy        | Native                      |
| **Tooling**       | Protoc, Buf                 | Swagger, Postman            |
| **Best for**      | Service-to-service, streaming | Public APIs, web clients  |

---

## tRPC for TypeScript

```typescript
// server/router.ts
import { router, publicProcedure, protectedProcedure } from './trpc';
import { z } from 'zod';

export const appRouter = router({
  user: router({
    get: publicProcedure
      .input(z.object({ id: z.string() }))
      .query(async ({ input }) => {
        return db.user.findUnique({ where: { id: input.id } });
      }),
    create: protectedProcedure
      .input(z.object({
        name: z.string().min(1),
        email: z.string().email(),
      }))
      .mutation(async ({ input, ctx }) => {
        return db.user.create({ data: { ...input, createdBy: ctx.userId } });
      }),
  }),
});

export type AppRouter = typeof appRouter;

// client.ts - Full type inference, no codegen
const user = trpc.user.get.useQuery({ id: '123' });
const createUser = trpc.user.create.useMutation();
```

tRPC is ideal for monorepo full-stack TypeScript apps where client and server share the same codebase.

---

## Webhook Design Patterns

### Webhook Payload

```json
{
  "id": "evt_abc123",
  "type": "order.completed",
  "created_at": "2025-01-15T10:30:00Z",
  "data": {
    "order_id": "ord_456",
    "total": 99.99,
    "currency": "USD"
  }
}
```

### Signature Verification

```typescript
// Sign webhooks with HMAC-SHA256
import crypto from 'crypto';

function signWebhook(payload: string, secret: string): string {
  return crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
}

// Verify on receiving end
function verifyWebhook(payload: string, signature: string, secret: string): boolean {
  const expected = signWebhook(payload, secret);
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected),
  );
}
```

### Retry Strategy

```
Attempt 1: Immediately
Attempt 2: After 1 minute
Attempt 3: After 5 minutes
Attempt 4: After 30 minutes
Attempt 5: After 2 hours
Attempt 6: After 24 hours (final)

Failed webhooks: log, alert, manual retry UI
```

### Idempotency

```typescript
// Include idempotency key in webhook
// Receivers should deduplicate based on event ID
async function handleWebhook(event: WebhookEvent) {
  // Check if already processed
  const existing = await db.processedEvents.findUnique({
    where: { eventId: event.id },
  });
  if (existing) return { status: 'already_processed' };

  // Process and record
  await db.$transaction([
    processEvent(event),
    db.processedEvents.create({ data: { eventId: event.id } }),
  ]);
}
```

---

## API Versioning Strategies

| Strategy            | Example                          | Pros                     | Cons                      |
| ------------------- | -------------------------------- | ------------------------ | ------------------------- |
| **URL path**        | `/api/v1/users`                  | Explicit, easy to route  | URL pollution             |
| **Query parameter** | `/api/users?version=1`           | Optional parameter       | Easy to miss              |
| **Header**          | `Accept: application/vnd.api.v1` | Clean URLs               | Hidden, harder to test    |
| **Content negotiation** | `Accept: application/json;v=2` | Standards-based        | Complex to implement      |

**Recommendation:** URL path versioning for simplicity. Only bump major versions for breaking changes. Use additive, non-breaking changes within a version.

© travisjneuman · MIT · travisjneuman/.claude

Similar skills

All skills for Backend and APIs →

api-design by other authors comes first.

api-design affaan-m Provides REST API design standards covering resource naming, status codes, pagination, and error payloads. Use it when creating or auditing API contracts. CX Codex +1 7,500installs api-design Aaronontheweb A skill for Claude Code and five other coding agents that enforces extend-only public API design. It activates on signature changes, wire format planning, and pull request reviews where breaking changes are possible. CX Codex +1 702installs api-design margelo The api-design skill shapes and reviews public APIs for TypeScript, JavaScript, React, and React Native libraries before implementation. CX Codex +1 1,400installs api-design OrchestKit api-design establishes design standards for REST, GraphQL, and gRPC contracts when editing endpoints or OpenAPI files. Triggers on route definitions and schema changes. CX Codex +1 211installs api-design Agent Skills Team api-design is a Claude Code skill that designs or refactors REST and GraphQL API contracts. It runs before implementation, while the interface shape is being agreed on. CX Codex +1 390installs api-error-design Samuel Berthe api-error-design walks an agent through designing what a public API returns on failure: codes, an RFC 9457 envelope, messages and retry signals. Useful when integrators must self-serve fixes. CX Codex +1 10,200installs api-architect curiositech api-architect is a Claude Code skill that guides REST, GraphQL, and gRPC API design, from contracts and schemas to documentation and specification checks. CX Codex +1 235installs api-design-patterns bobmatnyc The api-design-patterns skill for Claude Code is an architectural reference for REST, GraphQL, and gRPC, guiding endpoint structure, pagination, versioning, and error payloads. CX Codex +1 585installs api-contract-design Rudolf S. api-contract-design is a Claude Code skill for designing and checking REST, GraphQL, or hybrid API contracts before implementation. CX Codex +1 ★ 587repo stars public-api-design-review Samuel Berthe public-api-design-review runs a REST API surface, shipped or still on paper, through an eight-part checklist and splits every finding into Must-change or Improvement. CX Codex +1 10,200installs api-expert martinholovsky api-expert enforces OpenAPI 3.1 and OWASP security standards for REST, GraphQL, and gRPC APIs. Useful when building endpoints via TDD with pytest and httpx. CX Codex +1 258installs

From the same set117

The whole set →
android-development The android-development Claude Code skill supports Android app development with Kotlin and Jetpack Compose. It activates for work on Material Design or modern Android architecture. CX Codex +1 175installs websockets-realtime websockets-realtime is a Claude Code skill that guides real-time data setup for chats, live feeds, and collaborative editing. CX Codex +1 172installs risk-management Enterprise risk management guidelines for assessing operational, tech, and vendor risks. Helps build heat maps and business continuity frameworks. CX Codex +1 171installs innovation An innovation-management playbook the agent can consult: horizons, portfolio mix, ideation, Stage-Gate, venture capital and IP. Handy when product bets need sorting. CX Codex +1 170installs generic-static-design-system generic-static-design-system — a design system skill for static sites built purely with HTML, CSS, and vanilla JS. Guides the agent to build lightweight interfaces without Tailwind or build tools. CX Codex +1 168installs ai-ml-development ai-ml-development — a skill for Claude Code and Codex handling machine learning tasks. Activates when building training pipelines, fine-tuning LLMs, or assembling RAG applications. CX Codex +1 167installs flutter-development flutter-development — a skill for Claude Code provides project structure, Dart 3 patterns, and architecture guides across mobile, desktop, and web. Activates during Flutter app creation and Material Design implementation. CX Codex +1 166installs options-comparator options-comparator — a skill for Claude Code brings structured option comparison using weighted scoring matrices, trade-off analysis, and recommendation templates. Runs during vendor evaluations and strategy reviews. CX Codex +1 162installs

Project sponsors

Companies that keep this analytics open