{"_id":"@ainative/skill-api-design","name":"@ainative/skill-api-design","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@ainative/skill-api-design","version":"1.0.0","description":"FastAPI best practices, Pydantic models, RESTful endpoint design, error handling, and authentication patterns. Use when designing APIs, creating endpoints, or implementing backend logic.","main":"SKILL.md","keywords":["fastapi","pydantic","rest-api","api-design","authentication","jwt","backend","python","error-handling","validation","ainative","skill"],"author":{"name":"AINative Studio"},"license":"MIT","homepage":"https://ainative.studio/skills/api-design","repository":{"type":"git","url":"git+https://github.com/AINative-Studio/ainative-skills.git","directory":"skills/api-design"},"bugs":{"url":"https://github.com/AINative-Studio/ainative-skills/issues"},"engines":{"node":">=18.0.0"},"publishConfig":{"access":"public"},"ainative":{"skillName":"api-design","category":"backend","tags":["fastapi","pydantic","rest","authentication","backend"],"triggers":["api","endpoint","fastapi","pydantic","authentication","jwt","rest","backend"]},"_id":"@ainative/skill-api-design@1.0.0","gitHead":"6b796cac1c2fb43072eca570f442dd40a55c8cd9","_nodeVersion":"22.21.0","_npmVersion":"10.9.4","dist":{"integrity":"sha512-bsP+qcIh1iVsgJe/1me0N9+g1rxGsPbxRvZk9zLJpp/8MBObgXbZv0fComWdUY7CZilZkIbUMOA/IUblsSpZ5w==","shasum":"ce1d306cad3d1467dc0d06b4336d4b108b6999e2","tarball":"https://registry.npmjs.org/@ainative/skill-api-design/-/skill-api-design-1.0.0.tgz","fileCount":7,"unpackedSize":61452,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCID8Hdh8u8P18th2VIV6uMKb8Iiij6Fcw0ME7Qw80eXsJAiBng/xDi2enO7n/Y09f00V1OnHRy0miqXjDyDRqVzCnew=="}]},"_npmUser":{"name":"ainative-studio","email":"toby@rely.ventures"},"directories":{},"maintainers":[{"name":"ainative-studio","email":"toby@rely.ventures"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/skill-api-design_1.0.0_1767773578143_0.8519121796803377"},"_hasShrinkwrap":false}},"time":{"created":"2026-01-07T08:12:58.039Z","1.0.0":"2026-01-07T08:12:58.309Z","modified":"2026-01-07T08:12:58.554Z"},"maintainers":[{"name":"ainative-studio","email":"toby@rely.ventures"}],"description":"FastAPI best practices, Pydantic models, RESTful endpoint design, error handling, and authentication patterns. Use when designing APIs, creating endpoints, or implementing backend logic.","homepage":"https://ainative.studio/skills/api-design","keywords":["fastapi","pydantic","rest-api","api-design","authentication","jwt","backend","python","error-handling","validation","ainative","skill"],"repository":{"type":"git","url":"git+https://github.com/AINative-Studio/ainative-skills.git","directory":"skills/api-design"},"author":{"name":"AINative Studio"},"bugs":{"url":"https://github.com/AINative-Studio/ainative-skills/issues"},"license":"MIT","readme":"# API Design Skill\n\nExpert FastAPI backend architect specializing in RESTful API design, Pydantic data validation, and scalable backend systems.\n\n## Installation\n\n```bash\nnpm install @ainative/skill-api-design\n```\n\n## Usage\n\nActivate this skill when:\n- Designing new REST APIs or endpoints\n- Creating Pydantic models and schemas\n- Implementing authentication (JWT, OAuth)\n- Setting up error handling and validation\n- Structuring FastAPI applications\n- Working with OpenAPI/Swagger documentation\n\n## What's Included\n\n### Core Skill File\n- `SKILL.md` - Complete FastAPI and Pydantic expertise\n\n### Reference Documentation\n\n#### 1. Endpoint Patterns (`references/endpoint-patterns.md`)\n- Complete CRUD implementation examples\n- List endpoints with pagination and filtering\n- Nested resource patterns\n- Bulk operations\n- Search and filtering\n- Custom actions (publish, archive, etc.)\n\n#### 2. Pydantic Models (`references/pydantic-models.md`)\n- Base model architecture (Create, Update, Response)\n- Advanced validation patterns\n- Nested models and relationships\n- Dynamic models with field validation\n- Model inheritance patterns\n- Computed fields and properties\n\n#### 3. Error Handling (`references/error-handling.md`)\n- Standard error response models\n- Custom exception classes (ValidationError, NotFoundError, etc.)\n- Global exception handlers\n- Database error handling with retries\n- Validation helper functions\n\n#### 4. Authentication Patterns (`references/auth-patterns.md`)\n- Complete JWT authentication implementation\n- Password hashing with bcrypt\n- Token creation and verification\n- Protected endpoint dependencies\n- API key authentication\n- Role-based access control (RBAC)\n- OAuth2 password flow\n\n## Quick Examples\n\n### Complete API Endpoint\n\n```python\nfrom fastapi import APIRouter, HTTPException, Depends\n\nrouter = APIRouter(prefix=\"/api/v1/users\", tags=[\"users\"])\n\n@router.post(\"/\", status_code=201, response_model=UserResponse)\nasync def create_user(\n    user: UserCreate,\n    current_user=Depends(get_current_admin)\n):\n    \"\"\"Create a new user (admin only)\"\"\"\n    if await user_exists(user.email):\n        raise HTTPException(status_code=400, detail=\"Email already registered\")\n\n    hashed_password = hash_password(user.password)\n    new_user = await create_user_db(user, hashed_password)\n    return new_user\n```\n\n### Pydantic Model with Validation\n\n```python\nfrom pydantic import BaseModel, Field, validator\n\nclass UserCreate(BaseModel):\n    email: str = Field(..., pattern=r\"^[\\w\\.-]+@[\\w\\.-]+\\.\\w+$\")\n    password: str = Field(..., min_length=8)\n    age: int = Field(..., ge=13, le=120)\n\n    @validator('password')\n    def password_strength(cls, v):\n        if not any(c.isupper() for c in v):\n            raise ValueError('Password must contain uppercase letter')\n        if not any(c.isdigit() for c in v):\n            raise ValueError('Password must contain a digit')\n        return v\n```\n\n### JWT Authentication\n\n```python\nfrom fastapi import Depends\nfrom fastapi.security import HTTPBearer\n\nsecurity = HTTPBearer()\n\nasync def get_current_user(credentials=Depends(security)):\n    token = credentials.credentials\n    payload = jwt.decode(token, SECRET_KEY, algorithms=[\"HS256\"])\n    user_id = payload.get(\"sub\")\n    return await find_user(user_id)\n\n@router.get(\"/me\", response_model=UserResponse)\nasync def get_profile(current_user=Depends(get_current_user)):\n    return current_user\n```\n\n## Key Principles\n\n1. **RESTful Design** - Semantic HTTP methods, resource-oriented URLs\n2. **Pydantic First** - Define schemas before endpoints\n3. **Security by Default** - Always validate input, use dependency injection\n4. **Developer Experience** - Clear structure, comprehensive docs\n\n## Best Practices\n\n- Use `Field()` for validation and documentation\n- Separate Create/Update/Response models\n- Return appropriate HTTP status codes\n- Implement comprehensive error handling\n- Use dependency injection for auth and database\n- Document with docstrings (becomes OpenAPI docs)\n- Version your API (`/api/v1/`)\n- Use async/await for I/O operations\n\n## Requirements\n\n```python\nfastapi>=0.104.0\npydantic>=2.0.0\npython-jose[cryptography]>=3.3.0\npasslib[bcrypt]>=1.7.4\npython-multipart>=0.0.6\n```\n\n## OpenAPI Integration\n\nAll examples automatically generate:\n- Interactive Swagger UI at `/docs`\n- ReDoc documentation at `/redoc`\n- OpenAPI schema at `/openapi.json`\n\n## Testing Examples\n\n```python\nfrom fastapi.testclient import TestClient\n\nclient = TestClient(app)\n\ndef test_create_user():\n    response = client.post(\"/api/v1/users\", json={\n        \"email\": \"test@example.com\",\n        \"password\": \"SecurePass123!\",\n        \"age\": 25\n    })\n    assert response.status_code == 201\n    assert response.json()[\"email\"] == \"test@example.com\"\n```\n\n## License\n\nMIT\n\n## Support\n\nFor issues and questions, please visit the [GitHub repository](https://github.com/ainative/skills).\n","readmeFilename":"README.md","_rev":"1-b6f58f68550c32138a3294f7f503d991"}