Building a Complete RESTful Project API

# CHAPTER 29

Building a Complete RESTful Project API #

1. Introduction #

2. Learning Objectives #

• Architect the database schema for a multi-resource API.

• Design clean, RESTful URL endpoints for complex relationships.

• Implement token-based authentication and route protection.

• Structure a modular PHP codebase (Router, Controllers, Models).

• Apply validation, error handling, and status codes in a unified system.

3. Project Overview #

• Users can register and log in to receive a JWT or Bearer Token.

• Users can create, read, update, and delete "Projects".

• Users can create, read, update, and delete "Tasks" within a Project.

• Users can ONLY access their own Projects and Tasks (Authorization).

4. Database Architecture #

CREATE TABLE users (
    id INT AUTO_INCREMENT PRIMARY KEY,
    name VARCHAR(100),
    email VARCHAR(100) UNIQUE,
    password_hash VARCHAR(255),
    api_token VARCHAR(100) UNIQUE
);

CREATE TABLE projects (
    id INT AUTO_INCREMENT PRIMARY KEY,
    user_id INT, -- Foreign Key
    title VARCHAR(255),
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE
);

CREATE TABLE tasks (
    id INT AUTO_INCREMENT PRIMARY KEY,
    project_id INT, -- Foreign Key
    title VARCHAR(255),
    status ENUM('pending', 'in_progress', 'completed') DEFAULT 'pending',
    FOREIGN KEY (project_id) REFERENCES projects(id) ON DELETE CASCADE
);

5. API Endpoint Design (The Contract) #

Authentication:

• POST /api/v1/register (Creates user)

• POST /api/v1/login (Returns API Token)

Projects (Requires Token):

• GET /api/v1/projects (List user's projects)

• POST /api/v1/projects (Create project)

• GET /api/v1/projects/{id} (View project)

• PUT /api/v1/projects/{id} (Update project)

• DELETE /api/v1/projects/{id} (Delete project)

Tasks (Requires Token):

• GET /api/v1/projects/{projectid}/tasks (List tasks in a project)

• POST /api/v1/projects/{projectid}/tasks (Add task to a project)

• PUT /api/v1/tasks/{id} (Update specific task - *Notice it's flattened!*)

• DELETE /api/v1/tasks/{id} (Delete specific task)

6. System Architecture (PHP Folder Structure) #

/api/
  ├── .htaccess             # Routes all to index.php
  ├── index.php             # Front Controller / Router
  ├── config/
  │   └── database.php      # PDO Connection
  ├── controllers/
  │   ├── AuthController.php
  │   ├── ProjectController.php
  │   └── TaskController.php
  └── helpers/
      └── Response.php      # json_encode() helper

7. Core Implementation Steps #

Step 2: Validation & Creation (POST /projects) Inside ProjectController, read php://input. Validate that "title" is not empty. If invalid, return 422 Unprocessable Entity. If valid, execute PDO: INSERT INTO projects (userid, title) VALUES (:uid, :title). Return 201 Created.

Step 3: Authorization (GET /projects/5) Inside ProjectController, fetch project #5. Check if $project['userid'] == $currentUser['id']. If they don't match, return 403 Forbidden. If they match, return 200 OK with the JSON data.

Step 4: Pagination & Filtering (GET /tasks) Inside TaskController, check for $GET['status']. Apply LIMIT and OFFSET. Return the array wrapped in a {"meta": {}, "data": []} JSON structure.

• Returning the password hash: When a user logs in or views their profile, always unset($user['passwordhash']) before passing the array to jsonencode().

12. Coding Challenges #

13. MCQs with Answers #

14. Interview Questions #

• Q: Walk me through the architecture of a Task Management REST API. What do the database tables, URLs, and authentication mechanisms look like?

• Q: Explain why a client should NEVER send their user_id in a JSON POST payload when creating a resource.

• Q: How do you structure a raw PHP codebase to prevent index.php from becoming a 2000-line mess of code?

15. FAQs #

16. Summary #

17. Next Chapter Recommendation #