Skip to content
Skills Library
Programming · Planning

create-api-design

/create-api-design

Design a REST or GraphQL API from a feature specification when the user asks to design an API, create endpoints, define an API contract, or plan API resources

Licence
MIT
Last repository change
10.05.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
2
Deprecation

No signals detected. Repository changed on 10.05.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Design a REST or GraphQL API from a feature specification when the user asks to design an API, create endpoints, define an API contract, or plan API resources

Arguments

/create-api-design [feature name or resource to design API for]
Original author description

Design a REST or GraphQL API from a feature specification when the user asks to design an API, create endpoints, define an API contract, or plan API resources

How it works

  1. Overview
  2. Workflow
  3. Filename Convention
  4. API Design Document Format
  5. URL Design Rules
  6. Field Naming Rules
  7. Anti-patterns
Original SKILL.md headings · 354 lines, 1,650 words
SKILL.md preview
---
name: create-api-design
description: Design a REST or GraphQL API from a feature specification when the user asks to design an API, create endpoints, define an API contract, or plan API resources
author: chalk
version: "1.0.0"
metadata-version: "3"
allowed-tools: Read, Glob, Write, Grep
argument-hint: "[feature name or resource to design API for]"
read-only: false
destructive: false
idempotent: false
open-world: false
user-invocable: true
tags: api, design, docs
---

# Create API Design

## Overview

Design a complete, production-ready API from a feature specification or resource description. The output is a comprehensive API design document covering endpoints, schemas, error contracts, pagination, auth, rate limiting, and caching -- consistent with existing API patterns in the project.

## Workflow

1. **Read existing API patterns** -- Read `.chalk/docs/engineering/` for:
   - Existing API design documents (match naming, URL structure, and conventions)
   - Architecture docs describing the current API layer
   - Auth patterns and middleware
   - Error handling conventions
   - If no docs exist, scan the codebase for route definitions to infer patterns

2. **Scan codebase for current conventions** -- Use Grep to find:
   - Route definitions (e.g., `router.get`, `app.post`, `@GetMapping`, `@api_view`)
   - Error response shapes (look for error middleware, error classes)
   - Pagination patterns (cursor vs. offset, parameter names)
   - Auth middleware usage (JWT, API key, OAuth scopes)
   - Response envelope patterns (do responses wrap in `{ data, meta }` or return raw?)
   - Store these conventions; the new API must follow them exactly

3. **Determine the next document number** -- List files in `.chalk/docs/engineering/` matching `*_api_design_*.md`. Find the highest number and increment by 1.

4. **Clarify the resource and operations** -- From `$ARGUMENTS` and conversation context, identify:
   - The resource(s) being designed (nouns, not verbs)
   - The operations needed (CRUD, plus any domain-specific actions)
   - Who consumes this API (frontend, mobile, third-party, internal service)
   - Auth requirements (public, authenticated, role-based, scope-based)
   - Ask the user for clarification if the resource boundaries are unclear

5. **Design the endpoints** -- Follow REST conventions strictly:
   - Use plural nouns for resource paths (`/users`, not `/user`)
   - Use nested resources for ownership (`/users/{id}/posts`, not `/user-posts`)
   - Limit nesting to 2 levels maximum
   - Use HTTP methods correctly (GET reads, POST creates, PUT replaces, PATCH updates, DELETE removes)
   - Use query parameters for filtering, sorting, and pagination on collection endpoints
   - Use path parameters only for resource identifiers

6. **Define schemas** -- For each endpoint, define:
   - Request body JSON schema (for POST/PUT/PATCH)
   - Response body JSON schema (for all methods)
   - Query parameter schema (for GET collection endpoints)
   - Use consistent field naming (camelCase or snake_case -- match existing convention)

7. **Define error contract** -- Design a consistent error response shape used across all endpoints. Include validation errors, business logic errors, and system errors.

8. **Write the document** -- Save to `.chalk/docs/engineering/<n>_api_design_<resource_slug>.md`.

9. **Confirm** -- Tell the user the API design was created with its path and a summary of the endpoints defined.

## Filename Convention

```
<number>_api_design_<snake_case_resource>.md
```

Examples:
- `4_api_design_user_profiles.md`
- `8_api_design_billing_subscriptions.md`
- `11_api_design_notification_preferences.md`

## API Design Document Format

```markdown
# API Design: <Resource Name>

Last updated: <YYYY-MM-DD>

## Overview

<1-2 sentences describing what this API enables and who consumes it.>

## Base URL

<e.g., `/api/v1` -- match existing project convention>

## Authentication

<Describe auth requirements. Reference existing auth middleware if applicable.>

| Endpoint Pattern | Auth Required | Scopes / Roles |
|-----------------|---------------|----------------|
| `GET /resources` | Yes | `read:resources` |
| `POST /resources` | Yes | `write:resources` |
| `GET /resources/public` | No | — |

## Endpoints

### Resource Collection

#### List Resources

`GET /resources`

**Query Parameters:**

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `page` | integer | No | 1 | Page number (if offset pagination) |
| `limit` | integer | No | 20 | Items per page (max 100) |
| `sort` | string | No | `created_at` | Sort field |
| `order` | string | No | `desc` | Sort direction: `asc` or `desc` |
| `filter[status]` | string | No | — | Filter by status |

**Response: `200 OK`**

```json
{
  "data": [
    {
      "id": "res_abc123",
      "type": "resource",
      "attributes": {}
    }
  ],
  "meta": {
    "total": 142,
    "page": 1,
    "limit": 20,
    "total_pages": 8
  }
}
```

#### Create Resource

`POST /resources`

**Request Body:**

```json
{
  "name": "string (required, 1-255 chars)",
  "description": "string (optional, max 2000 chars)",
  "status": "string (optional, enum: draft|active|archived, default: draft)"
}
```

**Response: `201 Created`**

```json
{
  "data": {
    "id": "res_abc123",
    "type": "resource",
    "attributes": {
      "name": "Example",
      "description": null,
      "status": "draft",
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T10:30:00Z"
    }
  }
}
```

### Individual Resource

#### Get Resource

`GET /resources/{id}`

#### Update Resource

`PATCH /resources/{id}`

#### Delete Resource

`DELETE /resources/{id}`

<Continue for all endpoints...>

## Request / Response Schemas

### Resource Schema

| Field | Type | Constraints | Description |
|-------|------|------------|-------------|
| `id` | string | Read-only, prefixed | Unique identifier |
| `name` | string | Required, 1-255 chars | Display name |
| `created_at` | ISO 8601 | Read-only | Creation timestamp |
| `updated_at` | ISO 8601 | Read-only | Last modification timestamp |

## Error Contract

All errors follow a consistent shape:

```json
{
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "The requested resource does not exist.",
    "status": 404,
    "details": []
  }
}
```

### Validation Errors (`422`)

```json
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed.",
    "status": 422,
    "details": [
      {
        "field": "name",
        "constraint": "required",
        "message": "Name is required."
      },
      {
        "field": "email",
        "constraint": "format",
        "message": "Email must be a valid email address."
      }
    ]
  }
}
```

### Error Codes

| HTTP Status | Error Code | When Used |
|-------------|-----------|-----------|
| 400 | `BAD_REQUEST` | Malformed request syntax |
| 401 | `UNAUTHORIZED` | Missing or invalid auth token |
| 403 | `FORBIDDEN` | Valid auth but insufficient permissions |
| 404 | `RESOURCE_NOT_FOUND` | Resource does not exist |
| 409 | `CONFLICT` | Resource state conflict (e.g., duplicate) |
| 422 | `VALIDATION_ERROR` | Request body fails validation |
| 429 | `RATE_LIMITED` | Too many requests |
| 500 | `INTERNAL_ERROR` | Unexpected server error |

## Pagination Strategy

<Choose one and document it. Match existing project convention.>

### Offset Pagination (simpler, suitable for most cases)

- Parameters: `page` (1-indexed), `limit` (default 20, max 100)
- Response meta: `total`, `page`, `limit`, `total_pages`
- Drawback: inconsistent results if data changes between pages

### Cursor Pagination (for large or frequently changing datasets)

- Parameters: `cursor` (opaque string), `limit` (default 20, max 100)
- Response meta: `next_cursor`, `has_more`
- Advantage: consistent results regardless of data changes

## Rate Limiting

| Tier | Limit | Window | Scope |
|------|-------|--------|-------|
| Standard | 100 requests | 1 minute | Per API key |
| Elevated | 1000 requests | 1 minute | Per API key |
| Webhook delivery | 10 requests | 1 second | Per endpoint |

**Rate limit headers:**

```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1705312800
```

## Caching

| Endpoint | Cache Strategy | TTL | Invalidation |
|----------|---------------|-----|--------------|
| `GET /resources` | Private, no-store | — | — |
| `GET /resources/{id}` | Private, max-age | 60s | On PATCH/DELETE |
| `GET /resources/{id}/stats` | Private, max-age | 300s | On data change |

**Headers:**

```
Cache-Control: private, max-age=60
ETag: "abc123"
```

## Example Requests

### cURL

```bash
# List resources
curl -X GET "https://api.example.com/api/v1/resources?limit=10&sort=name" \
  -H "Authorization: Bearer <token>" \
  -H "Accept: application/json"

# Create resource
curl -X POST "https://api.example.com/api/v1/resources" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"name": "My Resource", "status": "active"}'
```

### Fetch (JavaScript)

```javascript
// List resources
const response = await fetch('/api/v1/resources?limit=10', {
  headers: {
    'Authorization': `Bearer ${token}`,
    'Accept': 'application/json',
  },
});
const { data, meta } = await response.json();

// Create resource
const response = await fetch('/api/v1/resources', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ name: 'My Resource', status: 'active' }),
});
```
```

## URL Design Rules

- **Plural nouns**: `/users`, `/orders`, `/invoices` -- never singular
- **Kebab-case**: `/user-profiles`, not `/userProfiles` or `/user_profiles`
- **No verbs in URLs**: `/orders/{id}/cancel` (POST) is acceptable for non-CRUD actions, but prefer state transitions via PATCH when possible
- **Max 2 levels of nesting**: `/users/{id}/orders` is fine; `/users/{id}/orders/{id}/items/{id}/variants` is not -- flatten it
- **Consistent ID format**: Use prefixed IDs (`usr_abc123`) or UUIDs, never auto-increment integers in URLs
- **Version in URL**: `/api/v1/` -- match existing project convention; if no convention exists, use URL-based versioning

## Field Naming Rules

- Match existing project convention (camelCase or snake_case) -- never mix
- Boolean fields: prefix with `is_`, `has_`, `can_` (e.g., `is_active`, `has_password`)
- Timestamps: suffix with `_at` (e.g., `created_at`, `deleted_at`)
- Counts: suffix with `_count` (e.g., `comment_count`)
- IDs: suffix with `_id` for foreign keys (e.g., `user_id`)

## Anti-patterns

- **Inconsistent error shapes** -- Every endpoint must return errors in the same structure. If one endpoint returns `{ "error": "message" }` and another returns `{ "errors": [{ "msg": "..." }] }`, clients cannot write generic error handling. Define the contract once and enforce it everywhere.
- **No pagination** -- Any endpoint that returns a list must be paginated. Unbounded list responses will eventually cause timeouts, OOM errors, or degraded client performance. There is no "the list is small" exception -- lists grow.
- **RPC-style URLs** -- `/api/getUser`, `/api/createOrder`, `/api/deleteInvoice` are RPC, not REST. Use resource nouns with HTTP methods: `GET /users/{id}`, `POST /orders`, `DELETE /invoices/{id}`.
- **No auth specification** -- Every endpoint must document its auth requirements. "Auth: TBD" is not a design -- it is a security gap. If auth is genuinely not yet decided, flag it as an unresolved question with your recommendation.
- **Breaking existing naming conventions** -- If the existing API uses `camelCase`, the new endpoints must use `camelCase`. Inconsistency across endpoints is worse than a suboptimal convention applied consistently.
- **Exposing internal IDs** -- Auto-increment database IDs leak information (total count, creation order) and are enumerable. Use UUIDs or prefixed opaque IDs.
- **No versioning strategy** -- APIs evolve. If there is no versioning mechanism, the first breaking change will be a crisis. Decide on URL-based or header-based versioning before shipping.
- **Inconsistent status codes** -- POST that returns 200 instead of 201, DELETE that returns 204 sometimes and 200 other times. Map each operation to its correct status code and be consistent.

Versions

The database has no other skills named create-api-design.

Identical content appears in 1 other GitHub folders. We show one copy with the highest score.

Database snapshot: 13.11.2026 · package version 59b56a5cfa1c (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100api-design
    Design clean and consistent APIs. Use when the user says "design an API", "API design review", "design these endpoints", "REST API for X", "GraphQL schema", "API contract", "how should this endpoint work", "review my API design", or wants to create or improve an API interface -…
  • 100design-api
    Design REST and GraphQL APIs: naming, versioning, error shapes, auth. Use when "design an API", "create endpoints", "REST vs GraphQL", or "API contract".
  • 96ditz-api
    Use when designing or reviewing REST/GraphQL endpoints.
  • 100api-design
    Design REST/GraphQL/OpenAPI contracts before implementation — API-first approach. Use when: API, endpoint, REST, GraphQL, OpenAPI, API contract, API design, HTTP endpoint, grpc, soap.
  • 100designing-apis
    Designs REST and GraphQL APIs including endpoints, error handling, versioning, and documentation. Use when creating new APIs, designing endpoints, reviewing API contracts, or when asked about REST, GraphQL, or API patterns.
  • 100api-and-interface-design
    指导稳定的 API 和接口设计。设计 API、模块边界或任何公共接口时使用。创建 REST 或 GraphQL endpoint、定义模块之间的类型契约,或建立前后端边界时使用。

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.