Requests

Okay, welcome back!

Through before docs, you have learned how to run and config our api.

This doc will tell you how to use.

Login

Send verification code

First of all, send verification code.

Request type: POST

Request url: https://< your ip>:< your port>/send_verification_code

Request body:

{
    "email": "your email"
}

Back data:

// VERIFICATION CODE RESPONSES
// ---------------------------
// All possible responses from the /send_verification_code endpoint

{
  // HTTP status code: 200
  // Success - Verification code sent
  "success": true,
  "message": "Verification code has been sent to your email"
}

{
  // HTTP status code: 500
  // Critical errors (server-side failures)
  "success": false,
  "message": "Email service not initialized"
}

{
  "success": false,
  "message": "Verification code storage failed"
}

{
  "success": false,
  "message": "Server error: <error_message>",
  "traceback": "<stack_trace>"  // Detailed error context for debugging
}

{
  // HTTP status code: 400
  // Client-side errors
  "success": false,
  "message": "Request body empty or invalid JSON"
}

{
  "success": false,
  "message": "Invalid email format"
}

{
  "success": false,
  "message": "Verification code sending failed"
}

Login

Second, start to login.

Way A: verification code

Request type: POST

Request URL: https://< your ip>:< your port>/login

Request body:

{
    "email": "your email",
    "code": "your email received code"
}

Way B: password

Request type: POST

Request URL: https://< your ip>:< your port>/login

Request body:

{
    "email": "your email",
    "password": "your password"
}

Back data:

// LOGIN ENDPOINT RESPONSES
// ------------------------
// All possible responses from the /login endpoint

{
  // 200 OK - New user registration successful
  "success": true,
  "message": "Account created successfully",
  "data": {
    "username": "<generated_username>",
    "uuid": "<numeric_user_id>"  // Sequential numeric ID instead of UUID
  }
}

{
  // 200 OK - Successful login
  "success": true,
  "message": "Login successful",
  "data": {
    "username": "<user_name>",
    "uuid": "<user_id>"
  }
}

{
  // 400 BAD REQUEST - Invalid request format
  "success": false,
  "message": "Request content must be JSON format",
  "content_type": "<actual_content_type>"  // Shows the unexpected content type
}

{
  // 400 BAD REQUEST - JSON parsing failure
  "success": false,
  "message": "Failed to parse JSON data",
  "raw_data": "<first_200_chars_of_raw_data>"  // For debugging malformed JSON
}

{
  // 400 BAD REQUEST - Missing email field
  "success": false,
  "message": "Email address is required"
}

{
  // 400 BAD REQUEST - Invalid email format
  "success": false,
  "message": "Invalid email format"
}

{
  // 503 SERVICE UNAVAILABLE - Redis connection failure
  "success": false,
  "message": "Authentication service unavailable",
  "error_code": "REDIS_CONNECTION_FAILED"  // Critical infrastructure issue
}

{
  // 500 INTERNAL SERVER ERROR - Redis operation failure
  "success": false,
  "message": "Internal server error",
  "error_code": "REDIS_OPERATION_FAILED"  // Database interaction error
}

{
  // 400 BAD REQUEST - Verification code mismatch
  "success": false,
  "message": "Verification code mismatch",
  "stored_code": true|false  // Debug field showing code existence
}

{
  // 400 BAD REQUEST - Email format error during registration
  "success": false,
  "message": "Invalid email format",
  "error_code": "INVALID_EMAIL_FORMAT"  // Special case for registration
}

{
  // 400 BAD REQUEST - User not found
  "success": false,
  "message": "User does not exist"
}

{
  // 400 BAD REQUEST - Password mismatch
  "success": false,
  "message": "Password mismatch",
  "hash_match": false  // Debug indicator for password verification
}

{
  // 400 BAD REQUEST - Missing credentials
  "success": false,
  "message": "Either password or verification code required",
  "provided_fields": ["<field1>", "<field2>"]  // Lists available request fields
}

{
  // 500 INTERNAL SERVER ERROR - Unhandled exception
  "success": false,
  "message": "Internal server error",
  "error": "<error_message>",
  "traceback": "<stack_trace>"  // Detailed error context for debugging
}