Building Standard REST APIs with PHP: From Basic Practices to MVC Architecture

Fundamental Concepts and Practices of REST APIs

When building REST APIs with PHP, beginners often start with simple scripts, such as directly processing request parameters and outputting results. However, real API development requires adherence to stricter standards. Consider the example code provided by the user:

$num1 = $_REQUEST['num1'];
$num2 = $_REQUEST['num2'];

$total = $num1 + $num2;
echo json_encode($total);

While this code achieves basic functionality, it lacks critical security and standardization elements. First, using $_REQUEST directly poses security risks, as it includes GET, POST, and COOKIE data, potentially leading to unexpected behavior. It is advisable to explicitly use $_POST for handling POST requests.

Data Validation and Error Handling

A core responsibility of an API is to ensure the validity of input data. For a numerical calculation API, it is essential to verify that the passed parameters are valid numbers. The following code demonstrates how to add basic validation:

if (!isset($_POST['num1']) || !isset($_POST['num2'])) {
    http_response_code(400);
    echo json_encode(['error' => 'Missing parameters']);
    exit;
}

$num1 = filter_var($_POST['num1'], FILTER_VALIDATE_FLOAT);
$num2 = filter_var($_POST['num2'], FILTER_VALIDATE_FLOAT);

if ($num1 === false || $num2 === false) {
    http_response_code(422);
    echo json_encode(['error' => 'Invalid numeric values']);
    exit;
}

Using the filter_var function to validate numeric types and appropriate HTTP status codes (e.g., 400 for bad request, 422 for unprocessable entity) enhances the semantic clarity of the API.

Response Header Configuration and JSON Formatting

A REST API should clearly inform the client about the format of the response. Setting the Content-Type header to application/json is a standard practice:

header('Content-Type: application/json');
$response = ['result' => $num1 + $num2];
echo json_encode($response, JSON_PRETTY_PRINT);

Using the JSON_PRETTY_PRINT option makes the output more readable for debugging purposes. A complete response should include structured data, not just raw numerical values.

Application of MVC Architecture in APIs

As API complexity increases, adopting a Model-Controller architecture improves code maintainability. Following the best answer's suggestion, a MathController class can be designed to handle mathematical operations:

class MathController {
    public function add($num1, $num2) {
        return $num1 + $num2;
    }
}

// Example routing handling
$controller = new MathController();
$result = $controller->add($num1, $num2);
$response = ['result' => $result];
echo json_encode($response);

This separation of concerns decouples business logic (model) from request handling (controller), facilitating extension and testing.

Advanced Framework Options

For more complex projects, using existing frameworks can accelerate development. As mentioned in supplementary answers, frameworks like Phalcon, Apigility, and Laravel offer built-in features such as routing, middleware, and authentication. For instance, creating an API endpoint in Laravel might require only a few lines of code:

// Laravel routing example
Route::post('/add', function (Request $request) {
    $validated = $request->validate([
        'num1' => 'required|numeric',
        'num2' => 'required|numeric'
    ]);
    return response()->json(['result' => $validated['num1'] + $validated['num2']]);
});

Frameworks automatically handle validation and JSON responses, reducing boilerplate code.

Testing and Debugging Recommendations

Using tools like Postman or cURL to test APIs ensures their behavior meets expectations. For example, sending a POST request via cURL:

curl -X POST -d "num1=5&num2=3" http://example.com/api/add

Should return a JSON response similar to {"result": 8}. Monitoring HTTP status codes and error messages is crucial for debugging.

Conclusion

Building standard REST APIs requires attention to data validation, response formatting, and architectural design. Starting with simple scripts and gradually introducing MVC patterns or frameworks improves code quality and scalability. Always set the correct Content-Type header and return results in structured JSON to ensure API interoperability and usability.