API Validation and Error Handling

# CHAPTER 18

API Validation and Error Handling #

1. Introduction #

2. Learning Objectives #

• Validate incoming JSON data for required fields and data types.

• Sanitize inputs to prevent Cross-Site Scripting (XSS).

• Structure standardized JSON error responses.

• Understand the 422 Unprocessable Entity status code.

• Provide actionable error messages to frontend developers.

3. Beginner-Friendly Explanation #

• If you don't send an email, the bouncer rejects you: "Email is required."

• If you send your age as "Banana", the bouncer rejects you: "Age must be a number."

• If you try to sneak in a script tag to hack the site, the bouncer confiscates it.

Validation is the process of examining the data *before* it ever touches your database to ensure it perfectly matches the expected rules.

4. Real-World Examples #

• Sign-up Forms: When an API rejects a password because it is "too short" or "missing a special character," that is backend validation at work.

• E-commerce: If you try to order -5 shirts, the API validates the quantity to ensure it is greater than 0.

5. Detailed Code Examples #

<?php
$data = json_decode(file_get_contents("php://input"), true);
$errors = [];

// 1. Required Field Validation
if (empty($data[&#039;email'])) {
    $errors[&#039;email'] = "Email field is required.";
} elseif (!filter_var($data[&#039;email'], FILTER_VALIDATE_EMAIL)) {
    // 2. Format Validation
    $errors[&#039;email'] = "Invalid email format.";
}

if (empty($data[&#039;age'])) {
    $errors[&#039;age'] = "Age field is required.";
} elseif (!is_numeric($data[&#039;age']) || $data['age'] < 18) {
    // 3. Type and Logic Validation
    $errors[&#039;age'] = "Age must be a number and 18 or older.";
}

// 4. Check if there are any errors
if (!empty($errors)) {
    // 422 Unprocessable Entity is the standard for validation failures
    http_response_code(422); 
    echo json_encode([
        "message" => "The given data was invalid.",
        "errors" => $errors
    ]);
    exit; // Stop execution! Do not touch the database!
}

// If we reach here, data is 100% valid. Safe to insert into DB.
echo json_encode(["message" => "User created safely."]);
?>

6. Request/Response Examples #

Bad Request Payload:

{
  "email": "not-an-email",
  "age": 12
}

Standardized Error Response (HTTP 422):

{
  "message": "Validation failed",
  "errors": {
    "email": [
      "The email address must be valid."
    ],
    "age": [
      "You must be at least 18 years old to register."
    ]
  }
}

7. HTTP Examples #

8. JSON Examples #

// Good Error Format
{
  "success": false,
  "error_code": "VALIDATION_FAILED",
  "details": {
    "password": "Password must contain a number."
  }
}

9. Best Practices #

• Validate Everything: Never assume data is safe. Validate lengths, types, formats, and ranges.

• Fail Fast: The moment you find a validation error, stop processing the script and return the error. Do not attempt to run database queries.

• Use Libraries: In real-world PHP, doing raw validation with if/else gets messy. Frameworks like Laravel use built-in validation classes. If writing core PHP, consider using a library like rakit/validation.

10. Common Mistakes #

• Returning HTML Errors: If your PHP script hits a fatal error, it might output raw HTML (like the orange Xdebug screens). This breaks API clients because they are expecting JSON. Always configure PHP to return errors as JSON in an API environment.

• Vague Error Messages: Returning {"error": "Bad Data"} is useless to a developer trying to use your API. Tell them exactly *which* field was bad and *why*.

11. Mini Exercises #

1. 1. What PHP function is explicitly designed to validate whether a string is a properly formatted email address?

12. Coding Challenges #

13. MCQs with Answers #

14. Interview Questions #

• Q: Explain the difference between returning a 400 Bad Request and a 422 Unprocessable Entity.

• Q: Why must validation occur on the backend API even if the frontend form has strict HTML5 validation (like required type="email")?

• Q: What is the structure of a good JSON validation error response?

15. FAQs #

16. Summary #

17. Next Chapter Recommendation #