# API

> API design and specification. REST, GraphQL, gRPC, OpenAPI, design an API, create API spec, validate my API, endpoint.

- Skill: `arbazkhan971/api` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add arbazkhan971/api`
- Raw SKILL.md: https://api.skillmd.com/api/skills/arbazkhan971/api/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: arbazkhan971 (https://skillmd.com/u/arbazkhan971)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/arbazkhan971/api

---


# API — Design & Specification

## Activate When
- User invokes `/godmode:api`
- User says "design an API", "create API spec", "write API docs"
- User says "validate my API", "is this API well-designed?"
- When building a new service or microservice that exposes endpoints
- When `/godmode:plan` identifies API-related tasks
- When `/godmode:review` flags API design issues
- User says "add an endpoint", "api endpoint", "add api endpoint"

## Workflow

### Step 1: Discovery & Context
Understand what the API needs to do before designing anything:

```
API DISCOVERY:
Project: <name and purpose>
Type: REST | GraphQL | gRPC | Hybrid
Consumers: <who will call this API — frontend, mobile, third-party, internal services>
Scale: <expected request volume — RPS, concurrent users>
Auth model: <API key, OAuth2, JWT, mTLS, none>
Existing APIs: <list any existing endpoints for consistency>
Constraints: <backward compatibility, regulatory, latency SLAs>
```
If the user hasn't specified, ask: "What kind of API are we designing? Who will consume it?"

### Step 2: Resource Modeling
Identify the core resources and their relationships:

```
RESOURCE MODEL:
  Resource: <Name>
  Description: <what it represents>
  Attributes:
  - id: string (UUID v4)
  - <field>: <type> (<constraints>)
  - <field>: <type> (<constraints>)
  - created_at: datetime (ISO 8601)
  - updated_at: datetime (ISO 8601)
  Relationships:
  - belongs_to: <Resource> (via <foreign_key>)
  - has_many: <Resource>
  ...
```
Rules:
- Use nouns for resource names, plural for collections
- Every resource has an `id`, `created_at`, `updated_at`
- Define relationships explicitly — no implicit joins
- Field types must map to the target format (JSON Schema for REST, SDL for GraphQL, protobuf for gRPC)

### Step 3: Endpoint Design (REST)
For REST APIs, design endpoints following RESTful conventions:

```
ENDPOINT CATALOG:
| Method | Path | Description |
|--|--|--|
| GET | /api/v1/<resources> | List <resources> (paginated) |
| POST | /api/v1/<resources> | Create a <resource> |
| GET | /api/v1/<resources>/:id | Get a single <resource> |
| PUT | /api/v1/<resources>/:id | Replace a <resource> |
| PATCH | /api/v1/<resources>/:id | Partial update a <resource> |
| DELETE | /api/v1/<resources>/:id | Delete a <resource> |

Nested resources:
| GET | /api/v1/<parents>/:id/<children> | List children of parent |
  ...
```
For **GraphQL**: Define Query (single + list with filter/pagination), Mutation (create, update, delete), and
typed response objects.

For **gRPC**: Define service with rpc methods (Get, List, Create, Update, Delete) using typed request/response messages.

### Step 4: Versioning Strategy
URL path versioning (`/api/v1/`) is recommended for public APIs (explicit, easy to route). Header versioning
(`Accept: application/vnd...`) is cleaner but less discoverable. Choose one and apply consistently.
### Step 5: Pagination Design
Design pagination for all list endpoints:

```
PAGINATION STRATEGY:

Option A — Offset/Limit (simple, most common):
  GET /api/v1/resources?offset=20&limit=10
  Response: { data: [...], total: 150, offset: 20, limit: 10 }
  Pros: Simple, random access
  Cons: Inconsistent with concurrent writes, slow on large datasets

Option B — Cursor-based (RECOMMENDED for large datasets):
  GET /api/v1/resources?cursor=<opaque_token>&limit=10
  Response: {
    data: [...],
  ...
```
### Step 6: Error Response Design
Define a consistent error response format across all endpoints:

```
ERROR RESPONSE FORMAT:
{
  "error": {
    "code": "<MACHINE_READABLE_CODE>",
    "message": "<Human-readable message for developers>",
    "details": [
      {
        "field": "<field_name>",
        "code": "<VALIDATION_CODE>",
        "message": "<Field-specific error message>"
      }
    ],
  ...
```
### Step 7: Rate Limiting Design
Design rate limiting strategy for all endpoints:

```
RATE LIMITING:
Algorithm: Token Bucket | Sliding Window | Fixed Window
Scope: Per API key | Per user | Per IP | Per endpoint

TIERS:
| Tier | Rate | Burst | Daily Cap |
|--|--|--|--|
| Free | 60/min | 10 | 1,000 |
| Standard | 600/min | 50 | 50,000 |
| Premium | 6,000/min | 200 | 500,000 |
| Internal | 60,000/min | 1,000 | Unlimited |

  ...
```
### Step 8: OpenAPI Specification Generation
Generate a complete OpenAPI 3.1 spec for the designed API:

```yaml
openapi: "3.1.0"
info:
  title: "<API Name>"
  version: "<version>"
  description: "<API description>"
  contact:
```
### Step 9: Validation
Validate the API design against best practices:

```
API DESIGN VALIDATION:
| Check | Status |
|--|--|
| Consistent naming (plural nouns) | PASS | FAIL |
| Proper HTTP method usage | PASS | FAIL |
| Correct status codes | PASS | FAIL |
| Error response consistency | PASS | FAIL |
| Pagination on all list endpoints | PASS | FAIL |
| Rate limiting defined | PASS | FAIL |
| Auth on protected endpoints | PASS | FAIL |
| Versioning strategy applied | PASS | FAIL |
| Request/response examples exist | PASS | FAIL |
  ...
```
If the project has an existing OpenAPI spec, validate it:
```bash
# Validate OpenAPI spec
npx @redocly/cli lint openapi.yaml
# or
npx swagger-cli validate openapi.yaml
```

### Step 10: API Documentation & Artifacts
Generate the deliverables:

1. **OpenAPI spec file**: `docs/api/<service>-openapi.yaml`
2. **API design doc**: `docs/api/<service>-api-design.md`
3. **Example request/response pairs**: embedded in the OpenAPI spec
4. **Postman/Insomnia collection**: exported from the OpenAPI spec (if requested)

```
API DESIGN COMPLETE:

Artifacts:
- OpenAPI spec: docs/api/<service>-openapi.yaml
- Design doc: docs/api/<service>-api-design.md
- Endpoints: <N> endpoints across <M> resources
- Validation: <PASS | NEEDS REVISION>

Next steps:
-> /godmode:contract — Generate contract tests for consumers
-> /godmode:build — Implement the API endpoints
-> /godmode:plan — Decompose implementation into tasks
```
Commit: `"api: <service> — <N> endpoints, <M> resources, OpenAPI spec generated"`

## Key Behaviors

```bash
# Validate and lint OpenAPI spec
npx @redocly/cli lint openapi.yaml
npx swagger-cli validate openapi.yaml
npx oasdiff diff openapi.yaml --base main --check
```
IF response time P95 > 200ms: add pagination or caching.
WHEN spec validation errors > 0: fix before implementing endpoints.
IF list endpoint returns > 100 items: require cursor pagination.

1. **Spec before code.** The spec IS the source of truth.
2. **Consistency is king.** Same naming, errors, pagination everywhere.
3. **Design for consumers.** Predictable, well-documented responses.
4. **Version from day one.** /api/v1/ is cheap insurance.
5. **Error messages help developers.** Field-specific, actionable.
6. **Rate limit everything.** Public: 60/min. Internal: 6000/min.
7. **Validate the spec.** Lint with tooling after every change.

## Flags & Options

| Flag | Description |
|--|--|
| (none) | Full API design workflow |
| `--type rest` | Design REST API (default) |
| `--type graphql` | Design GraphQL API |

## Auto-Detection

Before prompting the user, automatically detect API context:

```
AUTO-DETECT SEQUENCE:
1. Detect existing API framework:
   - grep for 'express', 'fastify', 'koa', 'hono' (Node.js)
   - grep for 'flask', 'fastapi', 'django' (Python)
   - grep for 'gin', 'echo', 'fiber' (Go)
   - grep for 'spring-boot' (Java)
2. Detect existing API spec:
   - Find openapi.yaml, openapi.json, swagger.yaml, swagger.json
   - Find .proto files (gRPC)
   - Find schema.graphql, .graphql files (GraphQL)
3. Detect existing endpoints:
   - Scan route files for HTTP method + path patterns
  ...
```
<!-- tier-3 -->

## Quality Targets
- Target: <200ms p95 response time
- Target: >99.9% uptime for production APIs
- Payload limit: <5MB max response size

## HARD RULES

Never ask to continue. Loop autonomously until OpenAPI spec validates with zero errors.

```
MECHANICAL CONSTRAINTS — NON-NEGOTIABLE:
1. EVERY list endpoint MUST have pagination — no exceptions, no "we only have a few items."
2. EVERY endpoint MUST have a documented error response format — one schema for the entire API.
3. EVERY mutation endpoint MUST validate input — never trust client data.
4. EVERY public endpoint MUST have rate limiting defined.
5. NEVER put sensitive data in URLs or query parameters — use headers or body.
6. NEVER return stack traces or internal errors to API consumers — use error codes.
7. ALWAYS version from day one — /api/v1/ is cheap insurance.
8. ALWAYS validate the OpenAPI spec with tooling after generation.
9. git commit the spec file BEFORE implementing endpoints — spec is source of truth.
10. Log all API design decisions as TSV:
    ENDPOINT\tMETHOD\tPAGINATION\tAUTH\tRATE_LIMIT\tNOTES
```
## Keep/Discard Discipline
```
After EACH API design change:
  1. MEASURE: Run spectral/redocly lint on the OpenAPI spec. Run oasdiff for breaking changes.
  2. COMPARE: Does the spec validate with 0 errors? Are there 0 breaking changes?
  3. DECIDE:
     - KEEP if: spec validates AND 0 breaking changes AND all quality checks pass
     - DISCARD if: spec has validation errors OR breaking changes detected
  4. COMMIT kept changes. Revert discarded changes before the next resource.

Never keep a breaking change — add new fields additively instead.
```

## Stop Conditions
```
STOP when ANY of these are true:
  - OpenAPI spec validates with 0 errors
  - All list endpoints have pagination, all mutations have validation
  - Rate limiting and auth defined for every endpoint
  - User explicitly requests stop

DO NOT STOP because:
  - Mock server is not yet generated (spec is the source of truth)
  - One endpoint lacks example responses (add it, but spec is functional)
```