PHP - Building RESTful APIs in PHP

Building RESTful APIs in PHP involves creating web services that follow the principles of Representational State Transfer (REST). These APIs allow different systems, applications, or clients (such as web apps and mobile apps) to communicate with a server using standard HTTP methods.

Understanding REST Architecture

REST is an architectural style that uses HTTP protocols to perform operations on resources. A resource can be any data entity such as a user, product, or order.

In REST, each resource is identified by a unique URL, and operations are performed using HTTP methods:

  • GET: Retrieve data

  • POST: Create new data

  • PUT or PATCH: Update existing data

  • DELETE: Remove data

RESTful APIs are stateless, meaning each request from the client must contain all necessary information, and the server does not store session data between requests.

Key Principles of RESTful APIs

Statelessness

Each request is independent. The server does not retain client context between requests.

Client-Server Architecture

The client and server are separate, allowing independent development and scalability.

Uniform Interface

A consistent way of interacting with resources using standard HTTP methods and URLs.

Resource-Based

Everything is treated as a resource, accessed via endpoints such as:

/api/users
/api/products

Setting Up a Basic REST API in PHP

A simple REST API in PHP can be built using core PHP without frameworks.

Step 1: Routing Requests

You need to determine which endpoint and method are being accessed.

$requestMethod = $_SERVER['REQUEST_METHOD'];
$requestUri = $_SERVER['REQUEST_URI'];

Based on these values, you can route the request to the appropriate handler.

Step 2: Handling HTTP Methods

Example for handling different methods:

switch ($requestMethod) {
    case 'GET':
        // fetch data
        break;
    case 'POST':
        // create data
        break;
    case 'PUT':
        // update data
        break;
    case 'DELETE':
        // delete data
        break;
}

Step 3: Working with JSON Data

REST APIs commonly use JSON for data exchange.

Reading input:

$data = json_decode(file_get_contents("php://input"), true);

Sending response:

header("Content-Type: application/json");
echo json_encode($response);

Step 4: Database Interaction

Use a database (such as MySQL) to store and retrieve data.

Example:

$pdo = new PDO("mysql:host=localhost;dbname=test", "root", "");

$stmt = $pdo->query("SELECT * FROM users");
$users = $stmt->fetchAll(PDO::FETCH_ASSOC);

echo json_encode($users);

Structuring a REST API

A well-structured API separates concerns into layers:

  • Controller: Handles incoming requests

  • Service: Contains business logic

  • Model: Interacts with the database

Example structure:

/api
  /controllers
  /models
  /services

This improves maintainability and scalability.

HTTP Status Codes

Proper use of HTTP status codes is essential:

  • 200 OK: Successful request

  • 201 Created: Resource created

  • 400 Bad Request: Invalid input

  • 401 Unauthorized: Authentication required

  • 404 Not Found: Resource not found

  • 500 Internal Server Error: Server issue

Example:

http_response_code(404);
echo json_encode(["message" => "Resource not found"]);

Authentication and Security

REST APIs must be secured to prevent unauthorized access.

Common approaches:

  • Token-based authentication such as JWT

  • API keys

  • OAuth2

Additional security practices:

  • Use HTTPS

  • Validate and sanitize input

  • Implement rate limiting

  • Avoid exposing sensitive data

Versioning APIs

Versioning ensures backward compatibility when updating APIs.

Example:

/api/v1/users
/api/v2/users

This allows clients to continue using older versions without breaking.

Error Handling

Consistent error responses help clients understand issues.

Example:

echo json_encode([
    "error" => true,
    "message" => "Invalid request"
]);

Using Frameworks

While REST APIs can be built using core PHP, frameworks simplify development:

  • Laravel provides built-in routing, authentication, and validation

  • Symfony offers robust components for API development

Frameworks reduce boilerplate code and improve productivity.

Testing REST APIs

Testing ensures the API works correctly.

Tools commonly used:

  • Postman for manual testing

  • Automated testing frameworks

Test cases should cover:

  • Valid and invalid inputs

  • Authentication

  • Edge cases

Best Practices

  • Use meaningful and consistent endpoint names

  • Keep responses structured and predictable

  • Avoid deeply nested URLs

  • Use pagination for large datasets

  • Document APIs clearly using tools like OpenAPI

Conclusion

Building RESTful APIs in PHP involves designing a system that follows REST principles, handles HTTP requests properly, and returns structured JSON responses. By organizing code effectively, implementing security measures, and following best practices, developers can create scalable and maintainable APIs that serve as the backbone for modern web and mobile applications.