Fixmate API - Developer Documentation

📋 API Standards & Best Practices

🌍 Locale Support

All API responses support multi-language messages using i18next.

How to use: Add ?lang=en or ?lang=es to your requests, or use Accept-Language header.

Default: English (en)

📊 HTTP Status Codes

All responses use standard HTTP status codes from http-status-codes package.

Examples:

200 - Success
201 - Created
400 - Bad Request
401 - Unauthorized
404 - Not Found
500 - Internal Server Error

📦 Standard Response Format

All API responses follow a consistent structure:

{
  "status": "success" | "error",
  "statusCode": 200,
  "data": { ... },
  "message": "Localized message",
  "meta": {
    "timestamp": "2025-11-18T20:44:43.254Z",
    "version": "v1",
    "language": "en"
  }
}

🔧 Developer Guidelines

1. Response Messages Must Be Localized

All API response messages use i18n keys and are automatically translated based on the request language.

// ✅ Correct - Uses i18n key
ApiResponse.success(res, data, 'auth.loginSuccess', StatusCodes.OK, undefined, req);

// ❌ Incorrect - Hard-coded message
res.json({ message: 'Login successful' });

2. Use HTTP Status Codes Package

Always use constants from http-status-codes instead of magic numbers.

// ✅ Correct
import { StatusCodes } from 'http-status-codes';
ApiResponse.error(res, 'error.message', StatusCodes.BAD_REQUEST, undefined, undefined, req);

// ❌ Incorrect
res.status(400).json({ error: 'Bad request' });

3. Request Validation with Zod

All request data is validated using Zod schemas for type safety and automatic validation.

// Example validation schema
const registerSchema = z.object({
  body: z.object({
    email: z.string().email(),
    password: z.string().min(8),
    name: z.string().min(1)
  })
});

// Use in route
router.post('/register', validate(registerSchema), authController.register);

4. Error Handling

Use AppError class for operational errors with proper status codes and i18n keys.

// ✅ Correct
throw new AppError(
  'User not found',
  StatusCodes.NOT_FOUND,
  'auth.userNotFound'
);

// Global error handler automatically formats response

5. Rate Limiting

Different endpoints have appropriate rate limits:

General API: 200 requests per 15 minutes
Authentication: 5 requests per 15 minutes
Moderate: 20 requests per 15 minutes

📚 API Information

Base URL

http://localhost:5006/api/v1

API Version

v1 (Current)

Environment

production

Available Endpoints

POST /api/v1/auth/register - Register new user
POST /api/v1/auth/login - User login
POST /api/v1/auth/refresh - Refresh access token
GET /api/v1/auth/me - Get current user (Protected)
GET /api/v1/auth/google - Google OAuth login
POST /api/v1/auth/apple - Apple OAuth login
GET /health - Health check

💡 Example Responses

Success Response

{
  "status": "success",
  "statusCode": 200,
  "data": {
    "user": {
      "id": "uuid",
      "email": "user@example.com",
      "name": "John Doe",
      "username": "john.doe"
    },
    "token": "jwt-token",
    "refreshToken": "refresh-token"
  },
  "message": "Login successful",
  "meta": {
    "timestamp": "2025-11-18T20:44:43.254Z",
    "version": "v1",
    "language": "en"
  }
}

Error Response

{
  "status": "error",
  "statusCode": 400,
  "message": "Validation failed",
  "data": {
    "errors": [
      {
        "field": "email",
        "message": "Invalid email format"
      }
    ]
  },
  "meta": {
    "timestamp": "2025-11-18T20:44:43.254Z",
    "version": "v1",
    "language": "en"
  }
}

🚀 Fixmate API