RESTful APIs with PHP

Table of Contents

• Introduction to RESTful APIs
• Basics of HTTP Methods: GET, POST, PUT, DELETE
• Setting Up the Project
• Creating Endpoints: Handling Requests and Responses
• Returning JSON Responses
• Using URL Parameters and Query Strings
• Authentication and Authorization
• Error Handling in REST APIs
• Practical Example: Building a Simple RESTful API in PHP
• Conclusion

Introduction to RESTful APIs

A RESTful API (Representational State Transfer) is a set of conventions and principles that use HTTP to interact with resources. A RESTful API allows clients to interact with the server to retrieve or modify resources, which could be data or any entity managed by the server. RESTful APIs are widely used in web development, mobile apps, and microservices architectures.

Key Principles of RESTful APIs:

1. Stateless: Each request from the client contains all the necessary information for the server to understand and process it.
2. Uniform Interface: REST defines a standard set of operations (HTTP methods) to interact with resources.
3. Client-Server Architecture: The client and server are independent, and the API acts as an intermediary between them.
4. Cacheable: Responses must explicitly define whether they can be cached by the client.
5. Layered System: The architecture can have multiple layers, such as load balancers, proxies, etc., between the client and the server.

The core of a RESTful API is the use of HTTP methods (GET, POST, PUT, DELETE) to perform CRUD operations (Create, Read, Update, Delete) on resources.

Basics of HTTP Methods: GET, POST, PUT, DELETE

In REST, the standard HTTP methods are mapped to CRUD operations on resources:

• GET: Retrieves data from the server (Read operation).
• POST: Sends data to the server to create a new resource (Create operation).
• PUT: Updates an existing resource with new data (Update operation).
• DELETE: Deletes a resource (Delete operation).

These HTTP methods are used in combination with URLs to identify the resources and interact with them.

Example:

• GET /users: Retrieve a list of users.
• GET /users/{id}: Retrieve a specific user by ID.
• POST /users: Create a new user.
• PUT /users/{id}: Update the user with the specified ID.
• DELETE /users/{id}: Delete the user with the specified ID.

Setting Up the Project

To build a RESTful API in PHP, you first need to set up your project environment. Ensure you have the following:

1. A PHP server (e.g., Apache or Nginx) running.
2. Composer for managing dependencies.
3. A basic project structure with a directory for your API files.

Example Project Structure:

/api
  /controllers
    UserController.php
  /models
    User.php
  /routes
    api.php
  .htaccess
  index.php

• controllers: Contains the logic to handle incoming API requests.
• models: Contains classes to interact with the database or other data sources.
• routes: Defines the endpoints of the API.
• index.php: The entry point that routes the requests to the correct controller.

Creating Endpoints: Handling Requests and Responses

To create a RESTful API, you will define several endpoints. Each endpoint corresponds to a specific operation, such as retrieving or creating a resource.

For instance, to retrieve a list of users, you can create an endpoint like /users. The following code shows how you would handle the request in PHP:

Step 1: Define the Endpoint in routes/api.php

<?php
// routes/api.php

$router->get('/users', 'UserController@getAllUsers');
$router->get('/users/{id}', 'UserController@getUserById');
$router->post('/users', 'UserController@createUser');
$router->put('/users/{id}', 'UserController@updateUser');
$router->delete('/users/{id}', 'UserController@deleteUser');

• These routes map HTTP methods (GET, POST, PUT, DELETE) to specific controller functions.

Step 2: Create Controller Functions in controllers/UserController.php

<?php
// controllers/UserController.php

class UserController {

    // Get all users
    public function getAllUsers() {
        $users = User::all(); // Retrieve all users from the database
        echo json_encode($users);
    }

    // Get a user by ID
    public function getUserById($id) {
        $user = User::find($id); // Retrieve the user from the database
        if ($user) {
            echo json_encode($user);
        } else {
            echo json_encode(['error' => 'User not found']);
        }
    }

    // Create a new user
    public function createUser() {
        $data = json_decode(file_get_contents("php://input"), true);
        $user = User::create($data); // Create a new user in the database
        echo json_encode($user);
    }

    // Update an existing user
    public function updateUser($id) {
        $data = json_decode(file_get_contents("php://input"), true);
        $user = User::update($id, $data); // Update the user in the database
        echo json_encode($user);
    }

    // Delete a user
    public function deleteUser($id) {
        $user = User::delete($id); // Delete the user from the database
        if ($user) {
            echo json_encode(['message' => 'User deleted']);
        } else {
            echo json_encode(['error' => 'User not found']);
        }
    }
}

In this example, the controller methods correspond to the routes and handle the requests for each resource. The data is returned as a JSON response.

Returning JSON Responses

RESTful APIs typically return data in the JSON format. To ensure that the responses are returned as JSON, you can set the appropriate headers and use json_encode() to encode the data.

Example of JSON Response:

header('Content-Type: application/json');
echo json_encode($data);

This tells the client that the response is in JSON format, making it easy for the client to parse the data.

Using URL Parameters and Query Strings

Often, you need to pass parameters in the URL to filter or modify the data being requested.

For example:

• GET /users?age=30: Retrieve all users aged 30.
• GET /users/{id}/posts: Retrieve all posts of a specific user.

You can retrieve these parameters using the $_GET superglobal in PHP:

$age = isset($_GET['age']) ? $_GET['age'] : null;

Authentication and Authorization

To secure your API, you will likely need to implement authentication and authorization. A common method is using API tokens or OAuth.

For simplicity, we’ll focus on API token-based authentication:

1. The client sends an Authorization header with an API token.
2. The server verifies the token and processes the request if the token is valid.

Here’s an example of how you might check the token in your controller:

$headers = apache_request_headers();
$token = isset($headers['Authorization']) ? $headers['Authorization'] : null;

if (!$token || !verifyToken($token)) {
    header('HTTP/1.1 401 Unauthorized');
    echo json_encode(['error' => 'Unauthorized']);
    exit;
}

The verifyToken() function would check the validity of the token against a database or an external service.

Error Handling in REST APIs

Proper error handling is essential in RESTful APIs to ensure that the client receives meaningful error messages when something goes wrong. You should return appropriate HTTP status codes along with the error message.

• 200 OK: Successful request.
• 201 Created: Resource created successfully.
• 400 Bad Request: Invalid request or missing parameters.
• 404 Not Found: Resource not found.
• 500 Internal Server Error: Unexpected error on the server.

Example of an error response:

header('HTTP/1.1 400 Bad Request');
echo json_encode(['error' => 'Invalid input']);

Practical Example: Building a Simple RESTful API in PHP

In this example, we will build a basic RESTful API that handles users and their data.

1. Database Model: Create a User model to interact with the database (MySQL).

class User {
    public static function all() {
        // Code to fetch all users from the database
    }

    public static function find($id) {
        // Code to fetch a user by ID
    }

    public static function create($data) {
        // Code to create a new user
    }

    public static function update($id, $data) {
        // Code to update user data
    }

    public static function delete($id) {
        // Code to delete a user
    }
}

2. API Controller: Create UserController to handle requests and return responses.
3. Routes: Define the routes to map HTTP methods to controller actions.

Conclusion

In this module, we learned how to build a simple RESTful API in PHP. We covered:

• Basic HTTP methods used in REST APIs.
• How to handle requests and responses using PHP.
• Working with JSON data.
• Authentication and error handling in APIs.
• Practical steps for creating a simple API.

With this knowledge, you can now create powerful and flexible RESTful APIs using PHP.