- Backend: FastAPI app with all models, services, schemas, routes - Admin Panel: Next.js dashboard with all modules (CRM, POS, repairs, warranties, billing, notifications, etc.) - Ecommerce: storefront (submodule) + product catalog - AI Agents: .agents/ skill library for Antigravity IDE - Docs: architecture, billing, notification gateway markdown - Submodules: Backend/OpenWA, Ecommerce/File 2/storefront
37 lines
1.3 KiB
Markdown
37 lines
1.3 KiB
Markdown
---
|
|
name: "API Design"
|
|
description: "Enforce RESTful standards and schema contracts on backend controllers"
|
|
---
|
|
|
|
# Skill: API Design
|
|
|
|
## 1. Purpose
|
|
Maintains standardized RESTful routing, status codes, request validation, and payload formats across API interfaces.
|
|
|
|
## 2. When to Use
|
|
When designing new routes, controller endpoints, or service interfaces.
|
|
|
|
## 3. Preconditions
|
|
* Pydantic/Zod schemas declared for request and response structures.
|
|
* FastAPI routers organized by resource tags.
|
|
|
|
## 4. Step-by-Step Checklist
|
|
1. Align routing paths with standard plural nouns (e.g. `/api/v1/orders`).
|
|
2. Use matching HTTP request verbs: GET (fetch), POST (create), PUT (update), DELETE (remove).
|
|
3. Bind explicit request and response models.
|
|
4. Use native HTTP status codes (200 OK, 201 Created, 400 Bad Request, 401 Unauthorized, 404 Not Found, 500 Internal Error).
|
|
|
|
## 5. Validation Checklist
|
|
* Swagger UI renders routes and payloads accurately.
|
|
* Route parameters validate cleanly against schemas.
|
|
|
|
## 6. Examples
|
|
```python
|
|
@router.post("/", response_model=OrderResponse, status_code=status.HTTP_201_CREATED)
|
|
def create_order(payload: OrderCreate, db: Session = Depends(get_db)):
|
|
return orderService.create(db, payload)
|
|
```
|
|
|
|
## 7. Failure Cases
|
|
* Returning custom unstructured success strings instead of JSON objects.
|
|
* Using GET methods to perform data modifications.
|