メニュー
Design and build professional APIs with REST, GraphQL, and gRPC. Master authentication, documentation, testing, and operational concerns.
デフォルトでは、最初にソースを確認する Prompt が選択されています。直接コマンドに切り替えるか、ローカルコピーをダウンロードすることもできます。
インストールを決める前に、SKILL.md と SkillsMP に表示されている付属ファイルをお読みください。
Codex または Claude でインストール この Prompt をコピーして Codex、Claude、または他のアシスタントに貼り付けると、Skill ページを確認してインストールできます。
直接コマンドでは確認用 Prompt が省略されます。実行前にソースを確認してください。
npx skills add https://github.com/pluginagentmarketplace/custom-plugin-backend --skill api-designコマンドは1行のまま表示されます。コピー前に横へスクロールして全体を確認してください。
ローカルで確認しますか？SkillsMP が現在取得できるファイルをダウンロードできます。
SKILL.md を表示中
Master architectural design with SOLID principles, design patterns, microservices, and event-driven systems. Learn to design scalable backend systems.
Backend authentication and authorization patterns. JWT, OAuth2, session management, RBAC, and secure token handling.
Master relational and NoSQL databases. Learn PostgreSQL, MySQL, MongoDB, Redis, and other technologies for data persistence, optimization, and scaling.
SOC 職業分類に基づく
| name | api-design |
| description | Design and build professional APIs with REST, GraphQL, and gRPC. Master authentication, documentation, testing, and operational concerns. |
| sasmp_version | 2.0.0 |
| bonded_agent | 03-api-development |
| bond_type | PRIMARY_BOND |
| atomic_operations | ["ENDPOINT_DESIGN","AUTHENTICATION_SETUP","DOCUMENTATION_GENERATION","RATE_LIMITING_CONFIG"] |
| parameter_validation | {"query":{"type":"string","required":true,"minLength":5,"maxLength":2000},"api_type":{"type":"string","enum":["rest","graphql","grpc","websocket"],"required":false},"auth_method":{"type":"string","enum":["jwt","oauth2","api_key","session"],"required":false}} |
| retry_logic | {"max_attempts":3,"backoff":"exponential","initial_delay_ms":1000} |
| logging_hooks | {"on_invoke":"skill.api-design.invoked","on_success":"skill.api-design.completed","on_error":"skill.api-design.failed"} |
| exit_codes | {"SUCCESS":0,"INVALID_INPUT":1,"SECURITY_ISSUE":2,"SCHEMA_ERROR":3} |
Bonded to: api-development-agent
# Invoke api-design skill
"Design a REST API for user management with authentication"
"Implement JWT authentication for my FastAPI app"
"Generate OpenAPI documentation for my endpoints"
| Paradigm | Best For | Performance | Complexity |
|---|---|---|---|
| REST | Public APIs, CRUD, simple | Good | Low |
| GraphQL | Complex data, mobile clients | Good | Medium |
| gRPC | Internal services, real-time | Excellent | Medium |
| WebSocket | Bi-directional real-time | Excellent | Medium |
Client type?
│
├─→ Public/Third-party → REST
│
├─→ Mobile with complex data → GraphQL
│
├─→ Internal microservices
│ ├─→ High performance needed → gRPC
│ └─→ Standard HTTP preferred → REST
│
└─→ Real-time bi-directional → WebSocket
# OpenAPI 3.1 Specification
openapi: 3.1.0
info:
title: User Management API
version: 1.0
from fastapi import Depends, HTTPException, status
from fastapi.security import OAuth2PasswordBearer
from jose import JWTError, jwt
from datetime import datetime, timedelta
SECRET_KEY = "your-secret-key"
ALGORITHM = "HS256"
ACCESS_TOKEN_EXPIRE_MINUTES = 30
oauth2_scheme = OAuth2PasswordBearer(tokenUrl="token")
def create_access_token(data: dict) -> str:
to_encode = data.copy()
expire = datetime.utcnow() + timedelta(minutes=ACCESS_TOKEN_EXPIRE_MINUTES)
to_encode.update({"exp": expire})
return jwt.encode(to_encode, SECRET_KEY, algorithm=ALGORITHM)
async def get_current_user(token: str = Depends(oauth2_scheme)):
credentials_exception = HTTPException(
status_code=status.HTTP_401_UNAUTHORIZED,
detail="Could not validate credentials",
headers={"WWW-Authenticate": "Bearer"},
)
try:
payload = jwt.decode(token, SECRET_KEY, algorithms=[ALGORITHM])
user_id: str = payload.get("sub")
if user_id is None:
raise credentials_exception
return user_id
except JWTError:
raise credentials_exception
from fastapi import FastAPI, Request
from slowapi import Limiter
from slowapi.util import get_remote_address
limiter = Limiter(key_func=get_remote_address)
app = FastAPI()
app.state.limiter = limiter
@app.get("/api/v1/resource")
@limiter.limit("100/minute")
async def get_resource(request: Request):
return {"data": "rate limited endpoint"}
2xx Success
├── 200 OK → Standard success
├── 201 Created → Resource created
├── 204 No Content → Success, no body
4xx Client Error
├── 400 Bad Request → Invalid input
├── 401 Unauthorized → Auth required
├── 403 Forbidden → Permission denied
├── 404 Not Found → Resource not found
├── 422 Unprocessable → Validation error
├── 429 Too Many Reqs → Rate limited
5xx Server Error
├── 500 Internal Error → Server error
├── 502 Bad Gateway → Upstream error
├── 503 Unavailable → Service down
| Issue | Cause | Solution |
|---|---|---|
| 401 Unauthorized | Invalid/expired token | Check token, refresh if needed |
| CORS errors | Missing headers | Configure CORS middleware |
| 429 Rate Limited | Too many requests | Implement backoff, cache |
| Slow endpoints | N+1 queries, no caching | Optimize queries, add cache |
curl -H "Authorization: Bearer <token>"# tests/test_api.py
import pytest
from fastapi.testclient import TestClient
from app.main import app
client = TestClient(app)
class TestUserAPI:
def test_create_user_returns_201(self):
response = client.post(
"/api/v1/users",
json={"email": "test@example.com", "password": "secure123"}
)
assert response.status_code == 201
assert "id" in response.json()
def test_get_user_requires_auth(self):
response = client.get("/api/v1/users/123")
assert response.status_code == 401
def test_get_user_with_valid_token(self, auth_headers):
response = client.get("/api/v1/users/123", headers=auth_headers)
assert response.status_code == 200
See references/ directory for:
API_GUIDE.md - Detailed API patternsopenapi-template.yaml - OpenAPI starter template