Skip to main content
skill CX Codex

designing-apis — Claude Code skill: REST and GraphQL

designing-apis — a Claude Code skill that designs REST and GraphQL APIs: structures endpoints, defines request and response formats, configures error handling and versioning.

MIT ★ 1,424 updated 2026-10-06

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add CloudAI-X/claude-workflow-v2
/plugin install project-starter@claude-workflow
Open on GitHub

What designing-apis does

The skill runs in Claude Code and includes a seven-step design checklist: from resource definition to validation. For REST, it covers URL patterns (GET /users/:id, POST /users), HTTP status codes (200, 201, 400, 401, 404, 429, etc.) and response structures for success, errors and pagination. For GraphQL, it shows how to write query types, mutations and input schemas.

Also includes authentication patterns (JWT, API keys), rate limiting headers, an OpenAPI template and a security checklist (HTTPS, input validation, CORS, no sensitive data in URLs).

What it helps with

  • design a REST API with correct endpoint structure and status codes
  • define a GraphQL schema with types, mutations and input parameters
  • plan API versioning and update strategy
  • set up error handling, authentication and rate limiting
  • validate API design before implementation

Example prompts for the agent

  • Design a REST API for an order tracking service with filtering and pagination
  • Show me how to structure a GraphQL schema for users and their orders
  • Review my API contract against best practices: endpoints, error codes, authentication

How to install designing-apis

1Plugin marketplace

/plugin marketplace add CloudAI-X/claude-workflow-v2
/plugin install project-starter@claude-workflow

This installs the whole project-starter plugin with all its skills

2Skills CLI (Vercel)

npx skills add CloudAI-X/claude-workflow-v2 --skill designing-apis -a claude-code

3Manually: put the files in place

~/.claude/skills/designing-apis/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/designing-apis/

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

Questions about designing-apis

How do I install designing-apis in Claude Code?

Run /plugin marketplace add CloudAI-X/claude-workflow-v2, then /plugin install project-starter@claude-workflow. Next, run npx skills add CloudAI-X/claude-workflow-v2 --skill designing-apis -a claude-code. The skill will be available at ~/.claude/skills/designing-apis/SKILL.md.

What does the designing-apis skill do?

It helps you design APIs by defining endpoint structure, request and response formats, error codes, versioning, authentication and rate limiting rules. It covers both REST and GraphQL with design and security checklists.

How does this skill compare REST and GraphQL?

REST uses URL endpoints and HTTP methods (GET, POST, PUT, DELETE); GraphQL uses a single entry point with query and mutation types. The skill shows both: for REST it covers path structure and status codes, for GraphQL it covers type schemas and input parameters.

Source text

SKILL.md · MIT
---
name: designing-apis
description: 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.
---

# Designing APIs

### When to Load

- **Trigger**: Designing REST or GraphQL endpoints, API contracts, versioning, request/response formats
- **Skip**: Internal-only code with no API surface

## API Design Workflow

Copy this checklist and track progress:

```
API Design Progress:
- [ ] Step 1: Define resources and relationships
- [ ] Step 2: Design endpoint structure
- [ ] Step 3: Define request/response formats
- [ ] Step 4: Plan error handling
- [ ] Step 5: Add authentication/authorization
- [ ] Step 6: Document with OpenAPI spec
- [ ] Step 7: Validate design against checklist
```

## REST API Design

### URL Structure

```
# Resource-based URLs (nouns, not verbs)
GET    /users              # List users
GET    /users/:id          # Get user
POST   /users              # Create user
PUT    /users/:id          # Replace user
PATCH  /users/:id          # Update user
DELETE /users/:id          # Delete user

# Nested resources
GET    /users/:id/orders   # User's orders
POST   /users/:id/orders   # Create order for user

# Query parameters for filtering/pagination
GET    /users?role=admin&status=active
GET    /users?page=2&limit=20&sort=-createdAt
```

### HTTP Status Codes

| Code | Meaning           | Use Case                   |
| ---- | ----------------- | -------------------------- |
| 200  | OK                | Successful GET, PUT, PATCH |
| 201  | Created           | Successful POST            |
| 204  | No Content        | Successful DELETE          |
| 400  | Bad Request       | Invalid input              |
| 401  | Unauthorized      | Missing/invalid auth       |
| 403  | Forbidden         | Valid auth, no permission  |
| 404  | Not Found         | Resource doesn't exist     |
| 409  | Conflict          | Duplicate, state conflict  |
| 422  | Unprocessable     | Validation failed          |
| 429  | Too Many Requests | Rate limited               |
| 500  | Internal Error    | Server error               |

### Response Formats

**Success Response:**

```json
{
  "data": {
    "id": "123",
    "type": "user",
    "attributes": {
      "name": "John Doe",
      "email": "[email protected]"
    }
  },
  "meta": {
    "requestId": "abc-123"
  }
}
```

**List Response with Pagination:**

```json
{
  "data": [...],
  "meta": {
    "total": 100,
    "page": 1,
    "limit": 20,
    "totalPages": 5
  },
  "links": {
    "self": "/users?page=1",
    "next": "/users?page=2",
    "last": "/users?page=5"
  }
}
```

**Error Response:**

```json
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid input data",
    "details": [
      {
        "field": "email",
        "message": "Must be a valid email address"
      }
    ]
  },
  "meta": {
    "requestId": "abc-123"
  }
}
```

## API Versioning

**URL Versioning (Recommended):**

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

**Header Versioning:**

```
Accept: application/vnd.example.v1+json
```

## Authentication Patterns

**JWT Bearer Token:**

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

**API Key:**

```
X-API-Key: your-api-key
```

## Rate Limiting Headers

```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1609459200
Retry-After: 60
```

## GraphQL Patterns

**Schema Design:**

```graphql
# Abbreviated: input, connection and error types omitted for brevity
type Query {
  user(id: ID!): User
  users(filter: UserFilter, pagination: Pagination): UserConnection!
}

type Mutation {
  createUser(input: CreateUserInput!): UserPayload!
  updateUser(id: ID!, input: UpdateUserInput!): UserPayload!
}

type User {
  id: ID!
  name: String!
  email: String!
  orders(first: Int, after: String): OrderConnection!
}

input CreateUserInput {
  name: String!
  email: String!
}

type UserPayload {
  user: User
  errors: [Error!]
}
```

## OpenAPI Specification Template

See [OPENAPI-TEMPLATE.md](OPENAPI-TEMPLATE.md) for the full OpenAPI 3.0 specification template.

## API Design Validation

After completing the design, validate against this checklist:

```
Validation Checklist:
- [ ] All endpoints use nouns, not verbs
- [ ] HTTP methods match operations correctly
- [ ] Consistent response format across endpoints
- [ ] Error responses include actionable details
- [ ] Pagination implemented for list endpoints
- [ ] Authentication defined for protected endpoints
- [ ] Rate limiting headers documented
- [ ] OpenAPI spec is complete and valid
```

If validation fails, return to the relevant design step and address the issues.

## Security Checklist

- [ ] HTTPS only
- [ ] Authentication on all endpoints
- [ ] Authorization checks
- [ ] Input validation
- [ ] Rate limiting
- [ ] Request size limits
- [ ] CORS properly configured
- [ ] No sensitive data in URLs
- [ ] Audit logging

© CloudAI-X · MIT · CloudAI-X/claude-workflow-v2

Similar skills

All skills for Backend and APIs →

From the same set46

The whole set →
plan Creates and maintains a structured PLAN.md file in your project root to track phases, task dependencies, and progress logs. CX Codex +1 ★ 1,424repo stars refactor-guided refactor-guided guides structural refactoring in small steps and runs tests after each change. It keeps feature work separate from code restructuring. CX Codex +1 ★ 1,424repo stars convex-backend convex-backend is a Claude Code skill that loads Convex guidelines for TypeScript functions, schemas, validators, queries, mutations, actions, subscriptions, and file storage. It supports type-safe backend development. CX Codex +1 ★ 1,424repo stars dependency-upgrade The dependency-upgrade command for Claude Code updates packages one by one, runs tests after each upgrade, and rolls back changes on failures. CX Codex +1 ★ 1,424repo stars parallel-analyze parallel-analyze starts four subagents at once: architecture, security, performance, testing. Their findings land in one report, ranked by priority. CX Codex +1 ★ 1,424repo stars managing-git managing-git guides Claude Code through Git workflows, branch naming conventions, Conventional Commits formatting, and pull request review checklists. CX Codex +1 ★ 1,424repo stars code-reviewer code-reviewer — a Claude subagent that reads the changed files first, then reports findings by severity: correctness, security, performance, tests. CX Codex ★ 1,424repo stars designing-architecture designing-architecture — a skill that guides you through selecting an architecture pattern, evaluating project size and team capacity, and structuring your codebase. CX Codex +1 ★ 1,424repo stars

Project sponsors

Companies that keep this analytics open