From framework-dev
Use this skill when the user asks about "API design", "REST API", "GraphQL schema", "endpoint design", "request response format", "API versioning", "API contracts", "resource naming", "HTTP methods", or needs guidance during Phase 3 (Planning) to define API specifications for the framework.
How this skill is triggered — by the user, by Claude, or both
Slash command
/framework-dev:api-design-principlesThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
This skill provides guidance on designing APIs during Phase 3 (Planning) of framework development. It covers contract-first design, REST and GraphQL patterns, and how to create specifications that enable multi-agent development.
This skill provides guidance on designing APIs during Phase 3 (Planning) of framework development. It covers contract-first design, REST and GraphQL patterns, and how to create specifications that enable multi-agent development.
The 03-api-planning/api-contracts.md file is the SINGLE SOURCE OF TRUTH for all API endpoints.
Before implementing ANY endpoint:
api-contracts.md to get the exact specificationBefore calling ANY endpoint:
api-contracts.md to get the correct pathIn long Claude Code sessions, context drift causes:
/api/user when contract says /api/usersThe fix: Always read the contract before writing code.
Define API contracts BEFORE implementation. This enables:
flowchart LR
Contract[API Contract] --> Backend[Backend Implementation]
Contract --> Frontend[Frontend Implementation]
Contract --> Tests[Contract Tests]
Contract --> SDK[Generated SDKs]
Create 03-api-planning/api-contracts.md with this structure:
# API Contracts
> ⚠️ **THIS FILE IS THE SOURCE OF TRUTH**
> Before implementing or calling any endpoint, read this file.
> Do not guess endpoints. Do not assume paths.
## Base Configuration
- Base URL: `/api/v1`
- Auth: Bearer token in `Authorization` header
- Content-Type: `application/json`
- All dates: ISO 8601 UTC
## Endpoints Index
| Method | Path | Description | Status |
|--------|------|-------------|--------|
| GET | /users | List all users | ✅ Implemented |
| POST | /users | Create user | ✅ Implemented |
| GET | /users/:id | Get user by ID | 🔄 In Progress |
| PUT | /users/:id | Update user | ⏳ Pending |
| DELETE | /users/:id | Delete user | ⏳ Pending |
---
## Endpoint Details
### GET /users
**Description:** List all users with pagination
**Authentication:** Required
**Query Parameters:**
| Param | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| page | integer | No | 1 | Page number |
| limit | integer | No | 20 | Items per page (max 100) |
| sort | string | No | createdAt | Sort field |
| order | string | No | desc | Sort direction (asc/desc) |
**Response 200:**
```json
{
"data": [
{
"id": "uuid",
"email": "string",
"name": "string",
"createdAt": "ISO8601",
"updatedAt": "ISO8601"
}
],
"meta": {
"page": 1,
"limit": 20,
"total": 100,
"totalPages": 5
}
}
Response 401: Unauthorized Response 429: Rate limited
Description: Create a new user
Authentication: Required (admin only)
Request Body:
{
"email": "string (required, valid email)",
"name": "string (required, 2-100 chars)",
"password": "string (required, min 8 chars)",
"role": "string (optional, default: 'user', enum: ['user', 'admin'])"
}
Response 201: ← NOTE: 201, not 200
{
"data": {
"id": "uuid",
"email": "string",
"name": "string",
"role": "string",
"createdAt": "ISO8601"
}
}
Response 400: Validation error Response 401: Unauthorized Response 409: Email already exists
---
## REST API Design Principles
### Resource Naming
Use nouns for resources, not verbs:
Good: GET /tasks - List tasks POST /tasks - Create task GET /tasks/{id} - Get task PUT /tasks/{id} - Update task DELETE /tasks/{id} - Delete task
Bad: GET /getTasks POST /createTask POST /deleteTask
### HTTP Methods
| Method | Purpose | Idempotent | Safe |
|--------|---------|------------|------|
| GET | Retrieve resource | Yes | Yes |
| POST | Create resource | No | No |
| PUT | Replace resource | Yes | No |
| PATCH | Partial update | No | No |
| DELETE | Remove resource | Yes | No |
### URL Structure
/api/v1/{resource}/{id}/{sub-resource}/{sub-id}
Examples: /api/v1/projects/123/tasks /api/v1/users/456/preferences /api/v1/teams/789/members/101
### Query Parameters
For filtering, sorting, and pagination:
GET /tasks?status=active&priority=high&sort=-createdAt&page=1&limit=20
Conventions:
---
## Response Structure Standards
### Success Response Envelope
```json
{
"data": {
"id": "task-123",
"type": "task",
"attributes": {
"title": "Implement login",
"status": "active"
}
},
"meta": {
"requestId": "uuid"
}
}
{
"data": [
{ "id": "1", "name": "Item 1" },
{ "id": "2", "name": "Item 2" }
],
"meta": {
"page": 1,
"limit": 20,
"total": 100,
"totalPages": 5
}
}
{
"error": {
"code": "VALIDATION_ERROR",
"message": "Invalid request",
"details": [
{
"field": "email",
"message": "Must be a valid email address"
}
],
"requestId": "uuid"
}
}
| Code | Meaning | When to Use |
|---|---|---|
| 200 | OK | Successful GET, PUT, PATCH |
| 201 | Created | Successful POST with new resource |
| 204 | No Content | Successful DELETE |
| 400 | Bad Request | Malformed request syntax |
| 401 | Unauthorized | Missing or invalid auth |
| 403 | Forbidden | Valid auth but insufficient permissions |
| 404 | Not Found | Resource doesn't exist |
| 409 | Conflict | Resource state conflict |
| 422 | Unprocessable Entity | Validation errors |
| 429 | Too Many Requests | Rate limit exceeded |
| 500 | Internal Server Error | Server-side failure |
⚠️ Important: Document the EXACT status code for each endpoint in the contract. POST usually returns 201, not 200.
Document validation in the contract:
CreateUser:
email:
type: string
required: true
format: email
maxLength: 255
name:
type: string
required: true
minLength: 2
maxLength: 100
pattern: "^[a-zA-Z ]+$"
password:
type: string
required: true
minLength: 8
pattern: "^(?=.*[a-z])(?=.*[A-Z])(?=.*\\d).*$"
role:
type: string
required: false
enum: [user, admin]
default: user
Document in the contract:
endpoints:
/api/v1/tasks:
GET:
auth: required
scopes: [tasks:read]
POST:
auth: required
scopes: [tasks:write]
/api/v1/public/status:
GET:
auth: none
rateLimits:
default:
requests: 100
window: 60s
authenticated:
requests: 1000
window: 60s
/api/v1/search:
requests: 20
window: 60s
api-contracts.md completely# Find all API calls in codebase
grep -r "fetch\|axios\|http" src/
# Verify each call matches contract
# Look for:
# - Correct HTTP method
# - Correct path
# - Correct request body structure
# - Correct response handling
When defining APIs during framework planning:
The API contract enables clean agent boundaries:
## Agent Assignment from Contract
### Backend Agent
- Implements all endpoints in api-contracts.md
- Must match contract exactly
- Updates status: ⏳ → 🔄 → ✅
### Frontend Agent
- Reads api-contracts.md for correct paths
- Must not guess endpoints
- Reports contract mismatches immediately
### QA Agent
- Generates tests from contract
- Validates response schemas
- Tests error scenarios
| Mistake | Problem | Fix |
|---|---|---|
POST /users returns 200 | Inconsistent with REST | Use 201 for creation |
| Missing pagination | List endpoints return all data | Add page/limit params |
| No error details | Client can't show specific errors | Add field-level errors |
| Guessing endpoints | Wrong paths in code | Always read contract first |
| Implicit schemas | Frontend assumes structure | Document every field |
| Missing auth requirements | Security gaps | Document auth per endpoint |
When the contract needs to change:
shared-context.mdWhen implementing code that calls an API:
1. Open `.framework-blueprints/03-api-planning/api-contracts.md`
2. Find the endpoint in the Index table
3. Read the full endpoint details:
- Method (GET/POST/PUT/DELETE)
- Exact path (watch for plurals: /users not /user)
- Query parameters (for GET)
- Request body schema (for POST/PUT)
- Response schema (what you'll receive)
- Status codes (especially success code)
4. Implement using EXACTLY these details
5. Do not assume or guess any part
For GraphQL APIs, document in api-contracts.md:
# Types
type User {
id: ID!
email: String!
name: String!
createdAt: DateTime!
}
# Queries
type Query {
user(id: ID!): User
users(page: Int, limit: Int): UserConnection!
}
# Mutations
type Mutation {
createUser(input: CreateUserInput!): UserPayload!
}
# Inputs
input CreateUserInput {
email: String!
name: String!
password: String!
}
Before finalizing API design:
npx claudepluginhub ankurjain1121/framework-developer-agentGuides designing API contracts in api-contract.md files with endpoint definitions, request/response schemas, TypeScript interfaces, and validation rules for backend-frontend coordination.
Guides stable API and interface design for REST/GraphQL endpoints, module boundaries, type contracts, component props, and frontend-backend separations.
Designs RESTful API contracts mapping user actions to HTTP endpoints with request/response schemas, error handling, and OpenAPI specs. For new API design, endpoint documentation, and contracts.