Api Design

Response Codes

Authentication Patterns

JWT Implementation

• Short-lived access tokens (15-60 min)
• Refresh tokens for session extension
• Include in Authorization header: Bearer <token>

Role-Based Access Control (RBAC)

• Define roles: owner, operator, viewer
• Check roles in middleware/dependencies
• Apply to endpoints: Depends(require_roles({"owner"}))

Request/Response Patterns

Standard Response Format

{
  "ok": true,
  "data": { ... },
  "meta": { "total": 100, "page": 1 }
}

Error Response Format

{
  "ok": false,
  "error": "error_code",
  "message": "Human readable message"
}

Pagination

• Use cursor or offset-based pagination
• Include metadata: total, page, limit, has_more

Versioning

• URL path: /api/v1/users
• Header: Accept: application/vnd.api.v1+json

Best Practices

1. Use nouns, not verbs in URLs
2. Return appropriate status codes
3. Validate input with schemas (Pydantic)
4. Log all operations for audit
5. Implement rate limiting
6. Use idempotency keys for POST/PUT
7. Document with OpenAPI/Swagger