Design APIs that are secure, scalable, and maintainable using RESTful, GraphQL, and event-driven patterns. Use when designing new APIs, evolving existing APIs, or establishing API standards for teams.
Design well-structured, scalable APIs using REST, GraphQL, or event-driven patterns. Focus on resource design, versioning, error handling, pagination, rate limiting, and security.
Use when:
Do NOT use for:
api-patterns skill for Express, FastAPI code)auth-security skill for JWT, sessions)testing-strategies skill)deploying-applications skill)Use nouns for resources, not verbs in URLs:
✓ GET /users List users
✓ GET /users/123 Get user 123
✓ POST /users Create user
✓ PATCH /users/123 Update user 123
✓ DELETE /users/123 Delete user 123
✗ GET /getUsers
✗ POST /createUser
Nest resources for relationships (limit depth to 2-3 levels):
✓ GET /users/123/posts
✓ GET /users/123/posts/456/comments
✗ GET /users/123/posts/456/comments/789/replies (too deep)
For complete REST patterns, see references/rest-design.md
| Method | Idempotent | Safe | Use For | Success Status | |--------|-----------|------|---------|----------------| | GET | Yes | Yes | Read resource | 200 OK | | POST | No | No | Create resource | 201 Created | | PUT | Yes | No | Replace entire resource | 200 OK, 204 No Content | | PATCH | No | No | Update specific fields | 200 OK, 204 No Content | | DELETE | Yes | No | Remove resource | 204 No Content, 200 OK |
Idempotent means multiple identical requests have the same effect as one request.
Success (2xx):
Client Errors (4xx):
Server Errors (5xx):
For complete status code guide, see references/rest-design.md
| Factor | REST | GraphQL | WebSocket | Message Queue | |--------|------|---------|-----------|---------------| | Public API | ⭐⭐⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐ | ⭐ | | Complex Data | ⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐ | ⭐⭐ | | Caching | ⭐⭐⭐⭐⭐ | ⭐⭐ | ⭐ | ⭐ | | Real-time | ⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | | Simplicity | ⭐⭐⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐ |
For detailed protocol selection, see references/protocol-selection.md
https://api.example.com/v1/users
https://api.example.com/v2/users
Pros: Explicit, easy to implement and test Cons: Maintenance overhead
Accept-Version: v1Accept: application/vnd.example.v1+json?version=1 (not recommended)Timeline:
Include deprecation headers:
Deprecation: true
Sunset: Sat, 31 Dec 2025 23:59:59 GMT
Link: </api/v2/users>; rel="successor-version"
For complete versioning guide, see references/versioning-strategies.md
{
"type": "https://api.example.com/errors/validation",
"title": "Validation Error",
"status": 400,
"detail": "One or more fields failed validation",
"errors": [
{
"field": "email",
"message": "Must be a valid email address",
"code": "INVALID_EMAIL"
}
]
}
Content-Type: application/problem+json
For complete error patterns, see references/error-handling.md
| Scenario | Strategy | Why | |----------|----------|-----| | Small datasets (<1000) | Offset-based | Simple, page numbers | | Large datasets (>10K) | Cursor-based | Efficient, handles writes | | Sorted data | Keyset | Consistent results | | Real-time feeds | Cursor-based | Handles new items |
GET /users?limit=20&offset=40
Response includes: limit, offset, total, currentPage
GET /users?limit=20&cursor=eyJpZCI6MTIzfQ==
Cursor is base64-encoded JSON with position information.
Response includes: nextCursor, hasNext
For implementation details, see references/pagination-patterns.md
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 73
X-RateLimit-Reset: 1672531200
When exceeded (429):
Retry-After: 3600
For implementation patterns, see references/rate-limiting.md
Authorization Code Flow (Web Apps):
Client Credentials Flow (Service-to-Service):
Define granular permissions:
read:users - Read user data
write:users - Create/update users
delete:users - Delete users
admin:* - Full admin access
Use header-based keys:
X-API-Key: sk_live_abc123xyz456
Best practices:
sk_live_*, sk_test_*For complete security patterns, see references/authentication.md
openapi: 3.1.0
info:
title: User Management API
version: 2.0.0
paths:
/users:
get:
summary: List users
parameters:
- name: limit
in: query
schema:
type: integer
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/UserList'
OpenAPI enables:
For complete OpenAPI examples, see examples/openapi/
AsyncAPI defines message-based APIs (WebSockets, Kafka, MQTT):
asyncapi: 3.0.0
info:
title: Order Events API
channels:
orders/created:
address: orders.created
messages:
orderCreated:
payload:
type: object
properties:
orderId:
type: string
For AsyncAPI examples, see examples/asyncapi/
type User {
id: ID!
username: String!
posts(limit: Int): [Post!]!
}
type Query {
user(id: ID!): User
users(limit: Int): [User!]!
}
type Mutation {
createUser(input: CreateUserInput!): User!
}
Use DataLoader to batch requests:
const userLoader = new DataLoader(async (userIds) => {
// Single query for all users
const users = await db.users.findByIds(userIds);
return userIds.map(id => users.find(u => u.id === id));
});
For GraphQL patterns, see references/graphql-design.md
| Scenario | Strategy | |----------|----------| | Small datasets | Offset-based | | Large datasets | Cursor-based | | Sorted data | Keyset | | Real-time feeds | Cursor-based |
| Factor | URL Path | Header | Media Type | |--------|----------|--------|------------| | Visibility | ⭐⭐⭐⭐⭐ | ⭐⭐ | ⭐⭐ | | Simplicity | ⭐⭐⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐ | | Best For | Most APIs | Internal APIs | Content negotiation |
Detailed guidance:
Working examples:
Validation and tooling:
Search for places (restaurants, cafes, etc.) via Google Places API proxy on localhost.
Interact with GitHub using the `gh` CLI. Use `gh issue`, `gh pr`, `gh run`, and `gh api` for issues, PRs, CI runs, and advanced queries.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Start voice calls via the OpenClaw voice-call plugin.
Notion API for creating and managing pages, databases, and blocks.
Gemini CLI for one-shot Q&A, summaries, and generation.
Category:developer