Admin

Software Developer

Add your Tutorial

21st June, 2026

325

PHP REST API Tutorial: Build RESTful APIs from Scratch

Introduction

REST APIs are the backbone of modern web and mobile applications. They allow different systems to communicate with each other using standard HTTP methods. Whether you're building a mobile app backend, a single-page application, or integrating third-party services, knowing how to build a REST API in PHP is an essential skill. This tutorial walks you through creating a complete RESTful API from scratch using pure PHP.

What is REST API?

REST (Representational State Transfer) is an architectural style for designing networked applications. A REST API uses HTTP requests to perform CRUD operations on resources. The key principles are stateless communication, resource-based URLs, standard HTTP methods, and JSON/XML responses.

Project Structure

project/
├── api/
│   ├── .htaccess          # URL rewriting
│   ├── index.php          # Entry point / Router
│   ├── config/
│   │   └── database.php   # Database connection
│   ├── controllers/
│   │   └── UserController.php
│   ├── models/
│   │   └── User.php
│   └── helpers/
│       └── Response.php   # JSON response helper
└── .htaccess              # Root redirect

Step 1: Database Setup

Create the database and users table:

CREATE DATABASE rest_api_demo;
USE rest_api_demo;

CREATE TABLE users (
    id INT AUTO_INCREMENT PRIMARY KEY,
    name VARCHAR(100) NOT NULL,
    email VARCHAR(150) NOT NULL UNIQUE,
    phone VARCHAR(20),
    status TINYINT(1) DEFAULT 1,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
);

-- Insert sample data
INSERT INTO users (name, email, phone) VALUES
('John Doe', '[email protected]', '1234567890'),
('Jane Smith', '[email protected]', '0987654321'),
('Mike Johnson', '[email protected]', '5555555555');

Step 2: Database Connection (config/database.php)

<?php

class Database {
    private $host = "localhost";
    private $db_name = "rest_api_demo";
    private $username = "root";
    private $password = "";
    private $conn;

    public function getConnection() {
        $this->conn = null;
        try {
            $this->conn = new PDO(
                "mysql:host=" . $this->host . ";dbname=" . $this->db_name . ";charset=utf8mb4",
                $this->username,
                $this->password,
                [
                    PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION,
                    PDO::ATTR_DEFAULT_FETCH_MODE => PDO::FETCH_ASSOC,
                    PDO::ATTR_EMULATE_PREPARES => false
                ]
            );
        } catch (PDOException $exception) {
            http_response_code(500);
            echo json_encode(["error" => "Database connection failed"]);
            exit;
        }
        return $this->conn;
    }
}

?>

Step 3: Response Helper (helpers/Response.php)

This helper standardizes all API responses in JSON format:

<?php

class Response {
    
    public static function json($data, $status_code = 200) {
        http_response_code($status_code);
        header('Content-Type: application/json; charset=utf-8');
        header('Access-Control-Allow-Origin: *');
        header('Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS');
        header('Access-Control-Allow-Headers: Content-Type, Authorization');
        echo json_encode($data, JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE);
        exit;
    }

    public static function success($data = [], $message = "Success", $status_code = 200) {
        self::json([
            'status' => true,
            'message' => $message,
            'data' => $data
        ], $status_code);
    }

    public static function error($message = "Error", $status_code = 400, $errors = []) {
        $response = [
            'status' => false,
            'message' => $message
        ];
        if (!empty($errors)) {
            $response['errors'] = $errors;
        }
        self::json($response, $status_code);
    }

    public static function notFound($message = "Resource not found") {
        self::error($message, 404);
    }

    public static function methodNotAllowed() {
        self::error("Method not allowed", 405);
    }
}

?>

Step 4: User Model (models/User.php)

<?php

class User {
    private $conn;
    private $table = "users";

    public function __construct($db) {
        $this->conn = $db;
    }

    // Get all users
    public function getAll($search = '', $limit = 10, $offset = 0) {
        $query = "SELECT id, name, email, phone, status, created_at, updated_at 
                  FROM " . $this->table;
        
        $params = [];
        
        if (!empty($search)) {
            $query .= " WHERE name LIKE :search OR email LIKE :search2";
            $params['search'] = "%$search%";
            $params['search2'] = "%$search%";
        }
        
        $query .= " ORDER BY id DESC LIMIT :limit OFFSET :offset";
        
        $stmt = $this->conn->prepare($query);
        
        foreach ($params as $key => $value) {
            $stmt->bindValue(":$key", $value);
        }
        
        $stmt->bindValue(':limit', (int)$limit, PDO::PARAM_INT);
        $stmt->bindValue(':offset', (int)$offset, PDO::PARAM_INT);
        $stmt->execute();
        
        return $stmt->fetchAll();
    }

    // Get total count for pagination
    public function getTotal($search = '') {
        $query = "SELECT COUNT(*) as total FROM " . $this->table;
        $params = [];
        
        if (!empty($search)) {
            $query .= " WHERE name LIKE :search OR email LIKE :search2";
            $params['search'] = "%$search%";
            $params['search2'] = "%$search%";
        }
        
        $stmt = $this->conn->prepare($query);
        foreach ($params as $key => $value) {
            $stmt->bindValue(":$key", $value);
        }
        $stmt->execute();
        
        return $stmt->fetch()['total'];
    }

    // Get single user by ID
    public function getById($id) {
        $query = "SELECT id, name, email, phone, status, created_at, updated_at 
                  FROM " . $this->table . " WHERE id = :id LIMIT 1";
        $stmt = $this->conn->prepare($query);
        $stmt->bindValue(':id', $id, PDO::PARAM_INT);
        $stmt->execute();
        
        return $stmt->fetch();
    }

    // Check if email exists (excluding current user for updates)
    public function emailExists($email, $exclude_id = null) {
        $query = "SELECT id FROM " . $this->table . " WHERE email = :email";
        $params = ['email' => $email];
        
        if ($exclude_id) {
            $query .= " AND id != :exclude_id";
            $params['exclude_id'] = $exclude_id;
        }
        
        $query .= " LIMIT 1";
        
        $stmt = $this->conn->prepare($query);
        foreach ($params as $key => $value) {
            $stmt->bindValue(":$key", $value);
        }
        $stmt->execute();
        
        return $stmt->rowCount() > 0;
    }

    // Create new user
    public function create($data) {
        $query = "INSERT INTO " . $this->table . " (name, email, phone) 
                  VALUES (:name, :email, :phone)";
        
        $stmt = $this->conn->prepare($query);
        $stmt->bindValue(':name', htmlspecialchars(strip_tags($data['name'])));
        $stmt->bindValue(':email', htmlspecialchars(strip_tags($data['email'])));
        $stmt->bindValue(':phone', htmlspecialchars(strip_tags($data['phone'] ?? '')));
        
        if ($stmt->execute()) {
            return $this->conn->lastInsertId();
        }
        return false;
    }

    // Update existing user
    public function update($id, $data) {
        $query = "UPDATE " . $this->table . " 
                  SET name = :name, email = :email, phone = :phone, status = :status 
                  WHERE id = :id";
        
        $stmt = $this->conn->prepare($query);
        $stmt->bindValue(':name', htmlspecialchars(strip_tags($data['name'])));
        $stmt->bindValue(':email', htmlspecialchars(strip_tags($data['email'])));
        $stmt->bindValue(':phone', htmlspecialchars(strip_tags($data['phone'] ?? '')));
        $stmt->bindValue(':status', (int)($data['status'] ?? 1), PDO::PARAM_INT);
        $stmt->bindValue(':id', $id, PDO::PARAM_INT);
        
        return $stmt->execute();
    }

    // Delete user
    public function delete($id) {
        $query = "DELETE FROM " . $this->table . " WHERE id = :id";
        $stmt = $this->conn->prepare($query);
        $stmt->bindValue(':id', $id, PDO::PARAM_INT);
        
        return $stmt->execute();
    }
}

?>

Step 5: User Controller (controllers/UserController.php)

<?php

require_once __DIR__ . '/../helpers/Response.php';
require_once __DIR__ . '/../models/User.php';

class UserController {
    private $user;
    
    public function __construct($db) {
        $this->user = new User($db);
    }

    // Handle incoming requests
    public function handleRequest($method, $id = null) {
        switch ($method) {
            case 'GET':
                $id ? $this->show($id) : $this->index();
                break;
            case 'POST':
                $this->store();
                break;
            case 'PUT':
                $id ? $this->update($id) : Response::error("User ID is required for update", 400);
                break;
            case 'DELETE':
                $id ? $this->destroy($id) : Response::error("User ID is required for delete", 400);
                break;
            default:
                Response::methodNotAllowed();
        }
    }

    // GET /api/users - List all users
    private function index() {
        $search = $_GET['search'] ?? '';
        $page = max(1, (int)($_GET['page'] ?? 1));
        $limit = min(50, max(1, (int)($_GET['limit'] ?? 10)));
        $offset = ($page - 1) * $limit;

        $users = $this->user->getAll($search, $limit, $offset);
        $total = $this->user->getTotal($search);
        
        $response_data = [
            'users' => $users,
            'pagination' => [
                'current_page' => $page,
                'per_page' => $limit,
                'total_records' => $total,
                'total_pages' => ceil($total / $limit),
                'has_next' => ($page * $limit) < $total,
                'has_previous' => $page > 1
            ]
        ];

        Response::success($response_data, "Users retrieved successfully");
    }

    // GET /api/users/{id} - Show single user
    private function show($id) {
        $user = $this->user->getById($id);
        
        if ($user) {
            Response::success(['user' => $user], "User retrieved successfully");
        } else {
            Response::notFound("User not found");
        }
    }

    // POST /api/users - Create new user
    private function store() {
        // Get JSON input
        $input = json_decode(file_get_contents('php://input'), true);
        
        // Validate input
        $errors = $this->validateInput($input);
        
        if (!empty($errors)) {
            Response::error("Validation failed", 422, $errors);
        }

        // Check if email already exists
        if ($this->user->emailExists($input['email'])) {
            Response::error("Email already exists", 409, ['email' => 'This email is already registered']);
        }

        // Create user
        $user_id = $this->user->create($input);
        
        if ($user_id) {
            $new_user = $this->user->getById($user_id);
            Response::success(['user' => $new_user], "User created successfully", 201);
        } else {
            Response::error("Failed to create user", 500);
        }
    }

    // PUT /api/users/{id} - Update user
    private function update($id) {
        // Check if user exists
        $existing_user = $this->user->getById($id);
        if (!$existing_user) {
            Response::notFound("User not found");
        }

        // Get JSON input
        $input = json_decode(file_get_contents('php://input'), true);
        
        // Validate input
        $errors = $this->validateInput($input, $id);
        
        if (!empty($errors)) {
            Response::error("Validation failed", 422, $errors);
        }

        // Check if email exists for other user
        if ($this->user->emailExists($input['email'], $id)) {
            Response::error("Email already taken", 409, ['email' => 'This email is already registered to another user']);
        }

        // Update user
        if ($this->user->update($id, $input)) {
            $updated_user = $this->user->getById($id);
            Response::success(['user' => $updated_user], "User updated successfully");
        } else {
            Response::error("Failed to update user", 500);
        }
    }

    // DELETE /api/users/{id} - Delete user
    private function destroy($id) {
        $user = $this->user->getById($id);
        
        if (!$user) {
            Response::notFound("User not found");
        }

        if ($this->user->delete($id)) {
            Response::success([], "User deleted successfully");
        } else {
            Response::error("Failed to delete user", 500);
        }
    }

    // Validate user input
    private function validateInput($input, $exclude_id = null) {
        $errors = [];

        if (empty($input['name'])) {
            $errors['name'] = "Name is required";
        } elseif (strlen($input['name']) < 2 || strlen($input['name']) > 100) {
            $errors['name'] = "Name must be between 2 and 100 characters";
        }

        if (empty($input['email'])) {
            $errors['email'] = "Email is required";
        } elseif (!filter_var($input['email'], FILTER_VALIDATE_EMAIL)) {
            $errors['email'] = "Invalid email format";
        }

        return $errors;
    }
}

?>

Step 6: API Entry Point / Router (api/index.php)

<?php

// Enable error reporting for development
error_reporting(E_ALL);
ini_set('display_errors', 0);

// Handle CORS preflight requests
if ($_SERVER['REQUEST_METHOD'] === 'OPTIONS') {
    header('Access-Control-Allow-Origin: *');
    header('Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS');
    header('Access-Control-Allow-Headers: Content-Type, Authorization');
    header('Access-Control-Max-Age: 86400');
    http_response_code(200);
    exit;
}

// Include required files
require_once __DIR__ . '/config/database.php';
require_once __DIR__ . '/controllers/UserController.php';

// Initialize database connection
$database = new Database();
$db = $database->getConnection();

// Parse the request URI
$request_uri = $_SERVER['REQUEST_URI'];
$base_path = '/api';

// Remove base path and query string
$path = parse_url($request_uri, PHP_URL_PATH);
$path = str_replace($base_path, '', $path);
$path = trim($path, '/');

// Split path into segments
$segments = explode('/', $path);

// Get resource name (first segment)
$resource = $segments[0] ?? '';

// Get resource ID (second segment)
$id = isset($segments[1]) && is_numeric($segments[1]) ? (int)$segments[1] : null;

// Get HTTP method
$method = $_SERVER['REQUEST_METHOD'];

// Route to appropriate controller
switch ($resource) {
    case 'users':
        $controller = new UserController($db);
        $controller->handleRequest($method, $id);
        break;
    
    case '':
        Response::json([
            'name' => 'PHP REST API',
            'version' => '1.0.0',
            'endpoints' => [
                'GET /api/users' => 'List all users',
                'GET /api/users/{id}' => 'Get single user',
                'POST /api/users' => 'Create new user',
                'PUT /api/users/{id}' => 'Update user',
                'DELETE /api/users/{id}' => 'Delete user'
            ]
        ]);
        break;
    
    default:
        Response::notFound("Endpoint not found");
}

?>

Step 7: URL Rewriting (api/.htaccess)

RewriteEngine On

# Handle Authorization Header
RewriteCond %{HTTP:Authorization} .
RewriteRule .* - [E=HTTP_AUTHORIZATION:%{HTTP:Authorization}]

# Redirect all requests to index.php
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule ^(.*)$ index.php [QSA,L]

Step 8: Testing the API

Get all users (GET):

Request: GET /api/users
Response: {
    "status": true,
    "message": "Users retrieved successfully",
    "data": {
        "users": [...],
        "pagination": {...}
    }
}

Get single user (GET):

Request: GET /api/users/1
Response: {
    "status": true,
    "message": "User retrieved successfully",
    "data": {
        "user": {
            "id": 1,
            "name": "John Doe",
            "email": "[email protected]"
        }
    }
}

Create user (POST):

Request: POST /api/users
Body: {
    "name": "New User",
    "email": "[email protected]",
    "phone": "1112223333"
}
Response: {
    "status": true,
    "message": "User created successfully",
    "data": {
        "user": {
            "id": 4,
            "name": "New User",
            "email": "[email protected]"
        }
    }
}

Update user (PUT):

Request: PUT /api/users/4
Body: {
    "name": "Updated User",
    "email": "[email protected]",
    "phone": "9998887777"
}
Response: {
    "status": true,
    "message": "User updated successfully"
}

Delete user (DELETE):

Request: DELETE /api/users/4
Response: {
    "status": true,
    "message": "User deleted successfully"
}

Pagination and search:

Request: GET /api/users?page=1&limit=5&search=john
Response: Returns filtered results with pagination info

Step 9: API Authentication (Simple Token-Based)

Add this to protect your API (helpers/Auth.php):

<?php

class Auth {
    
    private static $api_keys = [
        'abc123def456ghi789',  // Replace with database-stored keys
        'xyz987uvw654rst321'
    ];

    public static function authenticate() {
        $headers = getallheaders();
        $auth_header = $headers['Authorization'] ?? '';
        
        // Extract token from "Bearer {token}"
        if (preg_match('/Bearer\s+(.*)$/i', $auth_header, $matches)) {
            $token = $matches[1];
            
            if (in_array($token, self::$api_keys)) {
                return true;
            }
        }

        http_response_code(401);
        echo json_encode([
            'status' => false,
            'message' => 'Unauthorized. Invalid or missing API key.'
        ]);
        exit;
    }
}

// Usage in index.php:
// Auth::authenticate(); // Add this at the top to protect all routes

?>

Conclusion

You have now built a complete PHP REST API from scratch featuring:

Clean URL routing with .htaccess
MVC-like structure with controllers and models
Full CRUD operations for users
JSON request/response handling
Input validation and error handling
Pagination and search functionality
CORS support
Token-based authentication

This API can be extended with additional resources, JWT authentication, rate limiting, request logging, and API documentation using tools like Swagger or Postman collections.

Popular Tools for Developers

Free Sample Files (Image,Video,Audio,Documents) For Testing CSS Minifier Js Minifier JSON Viewer and Formatter

Popular Tools for Project Manager

SSL Checker

Popular Tools for Youtubers

BIC Code(Swift Code) for Adsense Generate YouTube Subscribe Button

Other Tools for Daily Life

Google drive sharelink to download link.

Admin

Related Tutorial

PHP Session Management – Complete Guide.

PHP MySQLi vs PDO – Which Database Extension to Use?.

PHP Send Email with SMTP PHPMailer Complete Tutorial.

PHP File Upload Tutorial: Secure Upload System with Validation.

PHP Login and Registration System – Complete Tutorial.

PHP CRUD Operations with MySQL: Complete Step-by-Step Guide.

Mastering DataTables: Implementing Column Filtering and Server-Side Processing with PHP.

Download XAMPP with Multiple PHP Versions: Easy Installation Guide.

A Guide to Types of Arrays in PHP.

How to Use Session Variables in PHP.

Popular Tools for Developers

Popular Tools for Project Manager

Popular Tools for Youtubers

Other Tools for Daily Life

About us

Find Online Tools

Quick links

Social links

Other