API Design Guide
Our conventions for building RESTful APIs that are consistent, well-documented, and easy to consume for frontend teams and third-party integrations.
URL Structure
/api/v1/usersList users with pagination, filtering, and sorting
/api/v1/users/:idGet a single user by ID
/api/v1/usersCreate a new user
/api/v1/users/:idPartially update a user
/api/v1/users/:idSoft-delete a user
Error Response Format
All errors follow a consistent JSON structure. This allows frontend teams to build reliable error handling without guessing the response shape.
{
"status": 422,
"code": "VALIDATION_ERROR",
"message": "Validation failed",
"errors": [
{ "field": "email", "message": "Invalid email format" }
]
}
Authentication
JWT Bearer Tokens
Short-lived access tokens (15 min) with refresh token rotation. Tokens contain user ID and role claims.
API Keys
For machine-to-machine communication. Prefixed with vit_ for identification. Hashed in the database, never stored in plain text.
Rate Limiting
Token bucket algorithm. Default: 100 req/min for authenticated, 20 req/min for public endpoints.
CORS
Whitelist specific origins. Never use wildcard (*) in production. Credentials mode for cookie-based auth.
Pagination Standard
Default for all list endpoints. Use ?cursor=xxx&limit=20 for efficient pagination on large datasets.
Optional fallback with ?page=1&per_page=20 for simpler clients, but discouraged for large collections.
Include { data: [...], meta: { cursor, has_more, total_count } } in every list response.
Building an API and want a second opinion? Get in touch for an API design review.