autohandai/api-design
api-design/SKILL.md
Design RESTful and GraphQL APIs following best practices. Use when creating new APIs, refactoring existing endpoints, or documenting API specifications. Handles OpenAPI, REST, GraphQL, versioning.
$ install --global
skillsauthnpx skillsauth add autohandai/community-skills api-designInstall this skill globally with one command. Works with Claude Code, Cursor, and Windsurf.
Security Scan Results
3 of 9 scanners reported clean
Some scanners were skipped, did not run, or reported a non-clean status. Review each row below.
3
Scanners Passed
9
Scanners in report
Clean
TrivyContainer and dependency vulnerability scanner
95%
Clean
SemgrepStatic code analysis for vulnerabilities
95%
Clean
mcp-scan (Snyk)Model Context Protocol security validation
95%
Skipped
Snyk (dep)Open source security scanning
50%
Skipped
Socket.devSupply chain security analysis
50%
Skipped
VirusTotalMulti-engine malware detection
50%
Skipped
CrowdStrikeAdvanced threat intelligence
50%
Skipped
OSV-ScannerOpen Source Vulnerability database check
50%
Skipped
OWASP Dep-Check
50%
Last scanned: Apr 15, 2026, 11:22 PM8.9s1 file scanned
SKILL.md
- name:
- api-design
- description:
- Design RESTful and GraphQL APIs following best practices. Use when creating new APIs, refactoring existing endpoints, or documenting API specifications. Handles OpenAPI, REST, GraphQL, versioning.
- license:
- Apache-2.0
- version:
- 1.0.0
- author:
- Agent Skills Team
- tags:
- api-design, REST, GraphQL, OpenAPI, versioning, backend
- platforms:
- Claude, ChatGPT, Gemini
API Design
When to use this skill
- Designing new REST APIs
- Creating GraphQL schemas
- Refactoring API endpoints
- Documenting API specifications
- API versioning strategies
- Defining data models and relationships
Instructions
Step 1: Define API requirements
- Identify resources and entities
- Define relationships between entities
- Specify operations (CRUD, custom actions)
- Plan authentication/authorization
- Consider pagination, filtering, sorting
Step 2: Design REST API
Resource naming:
- Use nouns, not verbs:
/usersnot/getUsers - Use plural names:
/users/{id} - Nest resources logically:
/users/{id}/posts - Keep URLs short and intuitive
HTTP methods:
GET: Retrieve resources (idempotent)POST: Create new resourcesPUT: Replace entire resourcePATCH: Partial updateDELETE: Remove resources (idempotent)
Response codes:
200 OK: Success with response body201 Created: Resource created successfully204 No Content: Success with no response body400 Bad Request: Invalid input401 Unauthorized: Authentication required403 Forbidden: No permission404 Not Found: Resource doesn't exist409 Conflict: Resource conflict422 Unprocessable Entity: Validation failed500 Internal Server Error: Server error
Example REST endpoint:
GET /api/v1/users # List users
GET /api/v1/users/{id} # Get user
POST /api/v1/users # Create user
PUT /api/v1/users/{id} # Update user
PATCH /api/v1/users/{id} # Partial update
DELETE /api/v1/users/{id} # Delete user
Step 3: Request/Response format
Request example:
POST /api/v1/users
Content-Type: application/json
{
"name": "John Doe",
"email": "[email protected]",
"role": "admin"
}
Response example:
HTTP/1.1 201 Created
Content-Type: application/json
Location: /api/v1/users/123
{
"id": 123,
"name": "John Doe",
"email": "[email protected]",
"role": "admin",
"created_at": "2024-01-15T10:30:00Z",
"updated_at": "2024-01-15T10:30:00Z"
}
Step 4: Error handling
Error response format:
{
"error": {
"code": "VALIDATION_ERROR",
"message": "Invalid input provided",
"details": [
{
"field": "email",
"message": "Invalid email format"
}
]
}
}
Step 5: Pagination
Query parameters:
GET /api/v1/users?page=2&limit=20&sort=-created_at&filter=role:admin
Response with pagination:
{
"data": [...],
"pagination": {
"page": 2,
"limit": 20,
"total": 100,
"pages": 5
},
"links": {
"self": "/api/v1/users?page=2&limit=20",
"first": "/api/v1/users?page=1&limit=20",
"prev": "/api/v1/users?page=1&limit=20",
"next": "/api/v1/users?page=3&limit=20",
"last": "/api/v1/users?page=5&limit=20"
}
}
Step 6: Authentication
Options:
- JWT (JSON Web Tokens)
- OAuth 2.0
- API Keys
- Session-based
Example with JWT:
GET /api/v1/users
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Step 7: Versioning
URL versioning (recommended):
/api/v1/users
/api/v2/users
Header versioning:
GET /api/users
Accept: application/vnd.api+json; version=1
Step 8: Documentation
Create OpenAPI 3.0 specification:
openapi: 3.0.0
info:
title: User Management API
version: 1.0.0
description: API for managing users
servers:
- url: https://api.example.com/v1
paths:
/users:
get:
summary: List users
parameters:
- name: page
in: query
schema:
type: integer
default: 1
- name: limit
in: query
schema:
type: integer
default: 20
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/User'
post:
summary: Create user
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UserCreate'
responses:
'201':
description: User created
content:
application/json:
schema:
$ref: '#/components/schemas/User'
components:
schemas:
User:
type: object
properties:
id:
type: integer
name:
type: string
email:
type: string
format: email
created_at:
type: string
format: date-time
UserCreate:
type: object
required:
- name
- email
properties:
name:
type: string
email:
type: string
format: email
Best practices
- Consistency: Use consistent naming, structure, and patterns
- Versioning: Always version your APIs from the start
- Security: Implement authentication and authorization
- Validation: Validate all inputs on the server side
- Rate limiting: Protect against abuse
- Caching: Use ETags and Cache-Control headers
- CORS: Configure properly for web clients
- Documentation: Keep docs up-to-date with code
- Testing: Test all endpoints thoroughly
- Monitoring: Log requests and track performance
Common patterns
Filtering:
GET /api/v1/users?role=admin&status=active
Sorting:
GET /api/v1/users?sort=-created_at,name
Field selection:
GET /api/v1/users?fields=id,name,email
Batch operations:
POST /api/v1/users/batch
{
"operations": [
{"action": "create", "data": {...}},
{"action": "update", "id": 123, "data": {...}}
]
}
GraphQL alternative
If REST doesn't fit, consider GraphQL:
type User {
id: ID!
name: String!
email: String!
posts: [Post!]!
createdAt: DateTime!
}
type Query {
users(page: Int, limit: Int): [User!]!
user(id: ID!): User
}
type Mutation {
createUser(input: CreateUserInput!): User!
updateUser(id: ID!, input: UpdateUserInput!): User!
deleteUser(id: ID!): Boolean!
}
References
- OpenAPI Specification
- REST API Tutorial
- GraphQL Best Practices
- HTTP Status Codes
Examples
Example 1: Basic usage
<!-- Add example content here -->Example 2: Advanced usage
<!-- Add advanced example content here -->Related Skills
autohandai/collecting-threat-intelligence-with-misp
development
VerifiedTrustedCommunity
MISP (Malware Information Sharing Platform) is an open-source threat intelligence platform for gathering, sharing, storing, and correlating Indicators of Compromise (IOCs) of targeted attacks, threat
9SKILL.mdUpdated Jul 16, 2026
autohandai/collecting-open-source-intelligence
tools
VerifiedTrustedCommunity
Collects and synthesizes open-source intelligence (OSINT) about threat actors, malicious infrastructure, and attack campaigns using publicly available data sources, passive reconnaissance tools, and dark web monitoring. Use when investigating external threat actor infrastructure, performing pre-engagement reconnaissance for authorized red team assessments, or enriching CTI reports with publicly available adversary context. Activates for requests involving Maltego, Shodan, OSINT framework, SpiderFoot, or infrastructure reconnaissance.
9SKILL.mdUpdated Jul 16, 2026
autohandai/collecting-indicators-of-compromise
development
VerifiedTrustedCommunity
Systematically collects, categorizes, and distributes indicators of compromise (IOCs) during and after security incidents to enable detection, blocking, and threat intelligence sharing. Covers network, host, email, and behavioral indicators using STIX/TAXII formats and threat intelligence platforms. Activates for requests involving IOC collection, indicator extraction, threat indicator sharing, compromise indicators, STIX export, or IOC enrichment.
9SKILL.mdUpdated Jul 16, 2026
autohandai/codebase-search
development
VerifiedTrustedCommunity
Search and navigate large codebases efficiently. Use when finding specific code patterns, tracing function calls, understanding code structure, or locating bugs. Handles semantic search, grep patterns, AST analysis.
9SKILL.mdUpdated Jul 16, 2026