88 lines
2.2 KiB
Text
88 lines
2.2 KiB
Text
---
|
|
description:
|
|
globs:
|
|
alwaysApply: false
|
|
---
|
|
# API Design Patterns
|
|
|
|
## API Route Structure
|
|
|
|
### Link Management API
|
|
Located in the `server/api/link/` directory, containing the following endpoints:
|
|
|
|
- [create.post.ts](mdc:server/api/link/create.post.ts): Create new short links
|
|
- [edit.put.ts](mdc:server/api/link/edit.put.ts): Edit existing links
|
|
- [delete.post.ts](mdc:server/api/link/delete.post.ts): Delete links
|
|
- [list.get.ts](mdc:server/api/link/list.get.ts): Get link lists
|
|
- [query.get.ts](mdc:server/api/link/query.get.ts): Query specific links
|
|
- [search.get.ts](mdc:server/api/link/search.get.ts): Search links
|
|
- [upsert.post.ts](mdc:server/api/link/upsert.post.ts): Create or update links
|
|
- [ai.get.ts](mdc:server/api/link/ai.get.ts): AI-generated slugs
|
|
|
|
### Other APIs
|
|
- [location.ts](mdc:server/api/location.ts): Geographic location information
|
|
- [verify.ts](mdc:server/api/verify.ts): Authentication
|
|
- `stats/`: Analytics-related APIs
|
|
- `logs/`: Logging-related APIs
|
|
- `ws/`: WebSocket-related APIs
|
|
|
|
## API Design Conventions
|
|
|
|
### HTTP Methods
|
|
- `GET`: Retrieve data (queries, lists)
|
|
- `POST`: Create resources or perform operations
|
|
- `PUT`: Update resources
|
|
- `DELETE`: Remove resources
|
|
|
|
### Response Format
|
|
```typescript
|
|
// Success response
|
|
{
|
|
success: true,
|
|
data: any
|
|
}
|
|
|
|
// Error response
|
|
{
|
|
success: false,
|
|
error: string,
|
|
code?: number
|
|
}
|
|
```
|
|
|
|
### Authentication
|
|
- Use Site Token for authentication
|
|
- Pass token in request header: `Authorization: Bearer <token>`
|
|
|
|
### Data Validation
|
|
- Use Zod for input validation
|
|
- Define validation schemas in `schemas/` directory
|
|
- Unified error handling and response format
|
|
|
|
### Cloudflare Integration
|
|
- Use Cloudflare Workers KV for data storage
|
|
- Leverage Cloudflare Analytics Engine for statistics
|
|
- Use Cloudflare AI for slug generation
|
|
|
|
## Error Handling
|
|
|
|
### Common Error Codes
|
|
- `400`: Bad request parameters
|
|
- `401`: Unauthorized access
|
|
- `403`: Insufficient permissions
|
|
- `404`: Resource not found
|
|
- `429`: Rate limit exceeded
|
|
- `500`: Internal server error
|
|
|
|
### Error Handling Pattern
|
|
```typescript
|
|
try {
|
|
// API logic
|
|
return { success: true, data: result }
|
|
} catch (error) {
|
|
return createError({
|
|
statusCode: 400,
|
|
statusMessage: error.message
|
|
})
|
|
}
|
|
```
|