ci3-rest-api

name: ci3-rest-api description: >- CodeIgniter 3 REST API patterns and conventions: MVC structure (controllers/api/, models/, views/), RESTful endpoints with chriskacerguis/RestServer library, JWT authentication using firebase/php-jwt, full CRUD patterns, form validation, database query builder, error handling, and security (XSS filtering, CSRF protection, SQL injection prevention). Designed for the code-igniter-3-fullstack agent building production-grade CI3 REST APIs with consistent response envelopes and secure defaults. version: "1.0.0" author: opencode-agent-kit license: MIT metadata: target_agent: code-igniter-3-fullstack stack: - CodeIgniter 3 - chriskacerguis/RestServer - firebase/php-jwt - MySQL - PostgreSQL - MVC Monolith tags: - codeigniter - rest-api - jwt - crud - mvc

CI3 REST API Skill

Target Agent: @code-igniter-3-fullstack
Stack: CodeIgniter 3 · RestServer · firebase/php-jwt · MySQL/PostgreSQL · MVC Monolith

Comprehensive reference for building production-grade REST APIs with CodeIgniter 3, covering project structure, controller patterns, JWT authentication flow, CRUD conventions, validation, security hardening, and error handling.

1. Project Structure

Standard CI3 MVC layout for REST API projects:

project_root/
├── application/
│   ├── controllers/
│   │   ├── api/               # REST API controllers
│   │   └── web/               # Optional web controllers
│   ├── models/                 # Data access layer
│   ├── views/                  # Templates (JSON views or HTML)
│   ├── config/                 # Configuration files
│   │   ├── rest.php            # RestServer config
│   │   ├── jwt.php             # JWT config (custom)
│   │   └── routes.php          # Route definitions
│   ├── libraries/              # Custom libraries (JWT helper, etc.)
│   ├── helpers/                # Custom helpers
│   ├── hooks/                  # Hooks (auth middleware, etc.)
│   ├── third_party/            # RestServer library
│   └── logs/                   # Error logs
├── assets/                     # Static assets (if any)
├── system/                     # CI3 system core
└── composer.json               # Dependency management (php-jwt, etc.)

Rationale

• controllers/api/ — All REST endpoints live here, separated from web controllers
• models/ — Single responsibility: one model per entity/table
• views/ — Can serve JSON via $this->output->set_content_type('application/json') or render HTML
• libraries/ — Custom classes like JWT_library or Auth_library
• config/rest.php — RestServer configuration (auth methods, rate limiting, response formats)
• config/jwt.php — Custom config for JWT secret, expiry, algorithms

2. RestServer Library Setup

Installation

1. Download chriskacerguis/codeigniter-restserver or add via Composer:

composer require chriskacerguis/codeigniter-restserver

2. Extend RestController instead of CI_Controller in API controllers:

defined('BASEPATH') OR exit('No direct script access allowed');

require_once APPPATH . '/libraries/REST_Controller.php';

use RestServer\REST_Controller;

class Users extends REST_Controller {
    // ...
}

REST Controller Configuration (application/config/rest.php)

Key configuration options:

Core Methods

3. JWT Authentication

Dependencies

composer require firebase/php-jwt

JWT Configuration (application/config/jwt.php)

<?php
defined('BASEPATH') OR exit('No direct script access allowed');

$config['jwt_key']            = getenv('JWT_SECRET') ?: 'your-secret-key-change-in-production';
$config['jwt_algorithm']      = 'HS256';
$config['jwt_expiry']         = 3600;        // 1 hour in seconds
$config['jwt_refresh_expiry'] = 604800;      // 7 days in seconds
$config['jwt_issuer']         = 'ci3-api';

JWT Library (application/libraries/JWT_library.php)

<?php
defined('BASEPATH') OR exit('No direct script access allowed');

use Firebase\JWT\JWT;
use Firebase\JWT\Key;
use Firebase\JWT\ExpiredException;

class JWT_library {
    protected $CI;
    protected $key;
    protected $algorithm;

    public function __construct() {
        $this->CI =& get_instance();
        $this->CI->load->config('jwt', TRUE);
        $this->key       = $this->CI->config->item('jwt_key', 'jwt');
        $this->algorithm = $this->CI->config->item('jwt_algorithm', 'jwt');
    }

    /**
     * Generate a JWT token for a given user.
     */
    public function encode(array $payload): string {
        $issuedAt  = time();
        $expiry    = $this->CI->config->item('jwt_expiry', 'jwt');

        $token = [
            'iss'  => $this->CI->config->item('jwt_issuer', 'jwt'),
            'iat'  => $issuedAt,
            'exp'  => $issuedAt + $expiry,
            'data' => $payload,
        ];

        return JWT::encode($token, $this->key, $this->algorithm);
    }

    /**
     * Decode and validate a JWT token.
     * Returns the payload data or throws on failure.
     */
    public function decode(string $token): object {
        try {
            $decoded = JWT::decode($token, new Key($this->key, $this->algorithm));
            return $decoded->data;
        } catch (ExpiredException $e) {
            throw new \RuntimeException('Token has expired');
        } catch (\Exception $e) {
            throw new \RuntimeException('Invalid token: ' . $e->getMessage());
        }
    }

    /**
     * Generate a refresh token with longer expiry.
     */
    public function encodeRefresh(array $payload): string {
        $issuedAt     = time();
        $refreshExpiry = $this->CI->config->item('jwt_refresh_expiry', 'jwt');

        $token = [
            'iss'  => $this->CI->config->item('jwt_issuer', 'jwt'),
            'iat'  => $issuedAt,
            'exp'  => $issuedAt + $refreshExpiry,
            'data' => $payload,
            'type' => 'refresh',
        ];

        return JWT::encode($token, $this->key, $this->algorithm);
    }
}

JWT Validation Hook / Middleware

Option A — Per-controller _is_logged_in() method:

/**
 * Verify JWT token from Authorization header.
 * Called at the start of protected methods.
 */
private function _is_logged_in(): bool {
    $this->load->library('JWT_library');

    $authHeader = $this->input->get_request_header('Authorization');

    if (!$authHeader) {
        $this->response([
            'status'  => false,
            'message' => 'Authorization header is missing',
        ], REST_Controller::HTTP_UNAUTHORIZED);
        return false;
    }

    $parts = explode(' ', $authHeader);
    if (count($parts) !== 2 || strtolower($parts[0]) !== 'bearer') {
        $this->response([
            'status'  => false,
            'message' => 'Invalid authorization format. Use: Bearer <token>',
        ], REST_Controller::HTTP_UNAUTHORIZED);
        return false;
    }

    try {
        $this->jwt_data = $this->jwt_library->decode($parts[1]);
        return true;
    } catch (\RuntimeException $e) {
        $this->response([
            'status'  => false,
            'message' => $e->getMessage(),
        ], REST_Controller::HTTP_UNAUTHORIZED);
        return false;
    }
}

Option B — CI3 Hook (global middleware):

In application/config/hooks.php:

$hook['post_controller_constructor'][] = [
    'class'    => 'Auth_hook',
    'function' => 'authenticate',
    'filename' => 'Auth_hook.php',
    'filepath' => 'hooks',
];

Login / Token Endpoint

<?php
defined('BASEPATH') OR exit('No direct script access allowed');

require_once APPPATH . '/libraries/REST_Controller.php';

use RestServer\REST_Controller;

class Auth extends REST_Controller {

    public function __construct() {
        parent::__construct();
        $this->load->model('User_model');
    }

    /**
     * POST /api/auth/login
     * Authenticate user and return JWT token.
     */
    public function login_post() {
        $this->load->library('form_validation');

        $this->form_validation->set_data([
            'email'    => $this->post('email'),
            'password' => $this->post('password'),
        ]);

        $this->form_validation->set_rules('email',    'Email',    'required|valid_email|trim');
        $this->form_validation->set_rules('password', 'Password', 'required|trim');

        if ($this->form_validation->run() === FALSE) {
            $this->response([
                'status'  => false,
                'message' => 'Validation failed',
                'errors'  => $this->form_validation->error_array(),
            ], REST_Controller::HTTP_UNPROCESSABLE_ENTITY);
            return;
        }

        $user = $this->User_model->get_by_email($this->post('email'));

        if (!$user || !password_verify($this->post('password'), $user->password)) {
            $this->response([
                'status'  => false,
                'message' => 'Invalid email or password',
            ], REST_Controller::HTTP_UNAUTHORIZED);
            return;
        }

        $this->load->library('JWT_library');

        $tokenPayload = [
            'user_id'  => $user->id,
            'email'    => $user->email,
            'role'     => $user->role ?? 'user',
        ];

        $token        = $this->jwt_library->encode($tokenPayload);
        $refreshToken = $this->jwt_library->encodeRefresh(['user_id' => $user->id]);

        $this->response([
            'status'  => true,
            'message' => 'Login successful',
            'data'    => [
                'token'         => $token,
                'refresh_token' => $refreshToken,
                'expires_in'    => $this->config->item('jwt_expiry', 'jwt'),
                'user'          => [
                    'id'    => $user->id,
                    'email' => $user->email,
                    'name'  => $user->name ?? '',
                    'role'  => $user->role ?? 'user',
                ],
            ],
        ], REST_Controller::HTTP_OK);
    }

    /**
     * POST /api/auth/refresh
     * Issue a new access token using a refresh token.
     */
    public function refresh_post() {
        $refreshToken = $this->post('refresh_token');

        if (!$refreshToken) {
            $this->response([
                'status'  => false,
                'message' => 'Refresh token is required',
            ], REST_Controller::HTTP_BAD_REQUEST);
            return;
        }

        $this->load->library('JWT_library');

        try {
            $data = $this->jwt_library->decode($refreshToken);
            $user = $this->User_model->get($data->user_id);

            if (!$user) {
                throw new \RuntimeException('User not found');
            }

            $newToken = $this->jwt_library->encode([
                'user_id' => $user->id,
                'email'   => $user->email,
                'role'    => $user->role ?? 'user',
            ]);

            $this->response([
                'status'  => true,
                'message' => 'Token refreshed',
                'data'    => [
                    'token'      => $newToken,
                    'expires_in' => $this->config->item('jwt_expiry', 'jwt'),
                ],
            ], REST_Controller::HTTP_OK);
        } catch (\RuntimeException $e) {
            $this->response([
                'status'  => false,
                'message' => $e->getMessage(),
            ], REST_Controller::HTTP_UNAUTHORIZED);
        }
    }
}

4. CRUD Patterns

Base CRUD Controller Template

<?php
defined('BASEPATH') OR exit('No direct script access allowed');

require_once APPPATH . '/libraries/REST_Controller.php';

use RestServer\REST_Controller;

class Products extends REST_Controller {

    protected $model_name = 'Product_model';
    protected $validation_rules = [];

    public function __construct() {
        parent::__construct();
        $this->load->model($this->model_name);
        $this->load->library('form_validation');

        // Set validation rules
        $this->validation_rules = [
            [
                'field' => 'name',
                'label' => 'Name',
                'rules' => 'required|min_length[3]|max_length[255]|trim|xss_clean',
            ],
            [
                'field' => 'price',
                'label' => 'Price',
                'rules' => 'required|numeric|greater_than[0]|trim',
            ],
            [
                'field' => 'description',
                'label' => 'Description',
                'rules' => 'trim|xss_clean',
            ],
            [
                'field' => 'category_id',
                'label' => 'Category',
                'rules' => 'required|integer|trim',
            ],
        ];
    }

    /**
     * GET /api/products
     * List all products with optional filtering and pagination.
     */
    public function index_get() {
        $this->is_logged_in(); // JWT gate — see Section 3

        $page    = (int) $this->get('page') ?: 1;
        $limit   = (int) $this->get('limit') ?: 20;
        $offset  = ($page - 1) * $limit;

        $filters = [];
        if ($this->get('search'))     $filters['search']       = $this->get('search');
        if ($this->get('category_id')) $filters['category_id'] = $this->get('category_id');
        if ($this->get('status'))     $filters['status']       = $this->get('status');

        $result = $this->{$this->model_name}->get_all($filters, $limit, $offset);
        $total  = $this->{$this->model_name}->count_all($filters);

        $this->response([
            'status'  => true,
            'message' => 'Products retrieved successfully',
            'data'    => [
                'items'    => $result,
                'total'    => (int) $total,
                'page'     => $page,
                'per_page' => $limit,
                'pages'    => ceil($total / $limit),
            ],
        ], REST_Controller::HTTP_OK);
    }

    /**
     * GET /api/products/:id
     * Get a single product by ID.
     */
    public function show_get($id) {
        $this->is_logged_in();

        $product = $this->{$this->model_name}->get($id);

        if (!$product) {
            $this->response([
                'status'  => false,
                'message' => 'Product not found',
            ], REST_Controller::HTTP_NOT_FOUND);
            return;
        }

        $this->response([
            'status'  => true,
            'message' => 'Product retrieved successfully',
            'data'    => $product,
        ], REST_Controller::HTTP_OK);
    }

    /**
     * POST /api/products
     * Create a new product.
     */
    public function create_post() {
        $this->is_logged_in();

        $input = [
            'name'        => $this->post('name'),
            'price'       => $this->post('price'),
            'description' => $this->post('description'),
            'category_id' => $this->post('category_id'),
            'status'      => $this->post('status') ?: 'active',
        ];

        $this->form_validation->set_data($input);
        $this->form_validation->set_rules($this->validation_rules);

        if ($this->form_validation->run() === FALSE) {
            $this->response([
                'status'  => false,
                'message' => 'Validation failed',
                'errors'  => $this->form_validation->error_array(),
            ], REST_Controller::HTTP_UNPROCESSABLE_ENTITY);
            return;
        }

        $id = $this->{$this->model_name}->create($input);

        if (!$id) {
            $this->response([
                'status'  => false,
                'message' => 'Failed to create product',
            ], REST_Controller::HTTP_INTERNAL_SERVER_ERROR);
            return;
        }

        $product = $this->{$this->model_name}->get($id);

        $this->response([
            'status'  => true,
            'message' => 'Product created successfully',
            'data'    => $product,
        ], REST_Controller::HTTP_CREATED);
    }

    /**
     * PUT /api/products/:id
     * Update an existing product.
     */
    public function update_put($id) {
        $this->is_logged_in();

        $existing = $this->{$this->model_name}->get($id);
        if (!$existing) {
            $this->response([
                'status'  => false,
                'message' => 'Product not found',
            ], REST_Controller::HTTP_NOT_FOUND);
            return;
        }

        $input = [
            'name'        => $this->put('name'),
            'price'       => $this->put('price'),
            'description' => $this->put('description'),
            'category_id' => $this->put('category_id'),
            'status'      => $this->put('status'),
        ];

        // Remove nulls to allow partial updates
        $input = array_filter($input, function ($value) {
            return $value !== null;
        });

        if (!empty($input)) {
            $this->form_validation->set_data($input);
            $this->form_validation->set_rules($this->validation_rules);

            if ($this->form_validation->run() === FALSE) {
                $this->response([
                    'status'  => false,
                    'message' => 'Validation failed',
                    'errors'  => $this->form_validation->error_array(),
                ], REST_Controller::HTTP_UNPROCESSABLE_ENTITY);
                return;
            }

            $updated = $this->{$this->model_name}->update($id, $input);

            if (!$updated) {
                $this->response([
                    'status'  => false,
                    'message' => 'Failed to update product',
                ], REST_Controller::HTTP_INTERNAL_SERVER_ERROR);
                return;
            }
        }

        $product = $this->{$this->model_name}->get($id);

        $this->response([
            'status'  => true,
            'message' => 'Product updated successfully',
            'data'    => $product,
        ], REST_Controller::HTTP_OK);
    }

    /**
     * DELETE /api/products/:id
     * Delete a product (soft or hard).
     */
    public function delete_delete($id) {
        $this->is_logged_in();

        $existing = $this->{$this->model_name}->get($id);
        if (!$existing) {
            $this->response([
                'status'  => false,
                'message' => 'Product not found',
            ], REST_Controller::HTTP_NOT_FOUND);
            return;
        }

        $deleted = $this->{$this->model_name}->delete($id);

        if (!$deleted) {
            $this->response([
                'status'  => false,
                'message' => 'Failed to delete product',
            ], REST_Controller::HTTP_INTERNAL_SERVER_ERROR);
            return;
        }

        $this->response([
            'status'  => true,
            'message' => 'Product deleted successfully',
        ], REST_Controller::HTTP_OK);
    }

    /**
     * Validate JWT token. Halts execution on failure.
     */
    private function is_logged_in(): void {
        $this->load->library('JWT_library');
        $authHeader = $this->input->get_request_header('Authorization');

        if (!$authHeader) {
            $this->response([
                'status'  => false,
                'message' => 'Authorization header is missing',
            ], REST_Controller::HTTP_UNAUTHORIZED);
            exit;
        }

        $parts = explode(' ', $authHeader);
        if (count($parts) !== 2 || strtolower($parts[0]) !== 'bearer') {
            $this->response([
                'status'  => false,
                'message' => 'Invalid authorization format. Use: Bearer <token>',
            ], REST_Controller::HTTP_UNAUTHORIZED);
            exit;
        }

        try {
            $this->jwt_data = $this->jwt_library->decode($parts[1]);
        } catch (\RuntimeException $e) {
            $this->response([
                'status'  => false,
                'message' => $e->getMessage(),
            ], REST_Controller::HTTP_UNAUTHORIZED);
            exit;
        }
    }
}

CRUD Method-to-Route Mapping

Routing (application/config/routes.php)

$route['api/products']             = 'api/products/index';
$route['api/products/(:num)']      = 'api/products/show/$1';
$route['api/products/create']      = 'api/products/create';
$route['api/products/update/(:num)'] = 'api/products/update/$1';
$route['api/products/delete/(:num)'] = 'api/products/delete/$1';

// Or use RestServer's built-in routing (auto-detect HTTP method)
$route['api/example']             = 'api/example';
$route['api/example/(:num)']      = 'api/example/show/$1';

5. Model Patterns (Database Query Builder)

Base Model Template

<?php
defined('BASEPATH') OR exit('No direct script access allowed');

class Product_model extends CI_Model {

    protected $table        = 'products';
    protected $primary_key  = 'id';
    protected $soft_delete  = TRUE;
    protected $allowed_fields = ['name', 'price', 'description', 'category_id', 'status'];

    public function __construct() {
        parent::__construct();
        $this->load->database();
    }

    /**
     * Get all records with filters, pagination, and ordering.
     */
    public function get_all(array $filters = [], int $limit = 20, int $offset = 0, string $order_by = 'created_at DESC'): array {
        $this->_apply_filters($filters);

        if ($this->soft_delete) {
            $this->db->where('deleted_at IS NULL');
        }

        $this->db->order_by($order_by);
        $this->db->limit($limit, $offset);

        $query = $this->db->get($this->table);
        return $query->result();
    }

    /**
     * Get a single record by primary key.
     */
    public function get($id): ?object {
        $this->db->where($this->primary_key, $id);

        if ($this->soft_delete) {
            $this->db->where('deleted_at IS NULL');
        }

        $query = $this->db->get($this->table);
        return $query->row() ?: null;
    }

    /**
     * Get by any column value.
     */
    public function get_by(string $field, $value): ?object {
        $this->db->where($field, $value);

        if ($this->soft_delete) {
            $this->db->where('deleted_at IS NULL');
        }

        $query = $this->db->get($this->table);
        return $query->row() ?: null;
    }

    /**
     * Get by email (convenience for auth).
     */
    public function get_by_email(string $email): ?object {
        return $this->get_by('email', $email);
    }

    /**
     * Create a new record. Returns inserted ID.
     */
    public function create(array $data): ?int {
        $data = $this->_filter_allowed($data);
        $data['created_at'] = date('Y-m-d H:i:s');
        $data['updated_at'] = date('Y-m-d H:i:s');

        if ($this->soft_delete) {
            $data['deleted_at'] = null;
        }

        return $this->db->insert($this->table, $data) ? $this->db->insert_id() : null;
    }

    /**
     * Update an existing record. Returns affected rows.
     */
    public function update($id, array $data): bool {
        $data = $this->_filter_allowed($data);
        $data['updated_at'] = date('Y-m-d H:i:s');

        $this->db->where($this->primary_key, $id);
        return $this->db->update($this->table, $data);
    }

    /**
     * Delete a record. Soft delete if enabled, hard delete otherwise.
     */
    public function delete($id): bool {
        if ($this->soft_delete) {
            return $this->update($id, ['deleted_at' => date('Y-m-d H:i:s')]);
        }

        $this->db->where($this->primary_key, $id);
        return $this->db->delete($this->table);
    }

    /**
     * Count total records (with optional filters).
     */
    public function count_all(array $filters = []): int {
        $this->_apply_filters($filters);

        if ($this->soft_delete) {
            $this->db->where('deleted_at IS NULL');
        }

        return $this->db->count_all_results($this->table);
    }

    /**
     * Apply safe WHERE conditions from filters.
     */
    protected function _apply_filters(array $filters): void {
        foreach ($filters as $field => $value) {
            if (in_array($field, $this->allowed_fields)) {
                if ($field === 'search') {
                    // Flexible search across multiple columns
                    $this->db->group_start();
                    $this->db->like('name', $value);
                    $this->db->or_like('description', $value);
                    $this->db->group_end();
                } else {
                    $this->db->where($field, $value);
                }
            }
        }
    }

    /**
     * Keep only allowed fields to prevent mass-assignment.
     */
    protected function _filter_allowed(array $data): array {
        return array_intersect_key($data, array_flip($this->allowed_fields));
    }
}

Query Builder Best Practices

6. Form Validation

Validation Rules Reference

CI3 built-in rules commonly used in REST APIs:

Validation Pattern for REST Controllers

// 1. Set input data explicitly (do not rely on $this->input->post())
$this->form_validation->set_data([
    'name'  => $this->post('name'),
    'email' => $this->post('email'),
]);

// 2. Define rules as array
$this->form_validation->set_rules([
    [
        'field' => 'name',
        'label' => 'Name',
        'rules' => 'required|min_length[3]|max_length[255]|trim|xss_clean',
    ],
    [
        'field' => 'email',
        'label' => 'Email',
        'rules' => 'required|valid_email|trim|xss_clean|is_unique[users.email]',
    ],
    [
        'field' => 'password',
        'label' => 'Password',
        'rules' => 'required|min_length[8]|trim',
    ],
]);

// 3. Run validation
if ($this->form_validation->run() === FALSE) {
    // Return structured error response
    $this->response([
        'status'  => false,
        'message' => 'Validation failed',
        'errors'  => $this->form_validation->error_array(),
    ], REST_Controller::HTTP_UNPROCESSABLE_ENTITY); // 422
    return;
}

Custom Validation Callback

/**
 * Custom callback: check that category exists.
 * Usage: 'rules' => 'callback_valid_category'
 */
public function valid_category($category_id): bool {
    $this->load->model('Category_model');
    $exists = $this->Category_model->get($category_id);

    if (!$exists) {
        $this->form_validation->set_message('valid_category', 'The selected category does not exist.');
        return false;
    }

    return true;
}

7. Error Handling

Consistent Error Response Envelope

Success:

{
  "status": true,
  "message": "Products retrieved successfully",
  "data": { ... }
}

Error (general):

{
  "status": false,
  "message": "Product not found"
}

Error (validation):

{
  "status": false,
  "message": "Validation failed",
  "errors": {
    "email": "The Email field must contain a valid email address.",
    "name": "The Name field is required."
  }
}

Error (server):

{
  "status": false,
  "message": "An internal error occurred. Please try again later."
}

HTTP Status Code Usage

Database Transaction with Try-Catch

/**
 * Example: create an order with items in a transaction.
 */
public function create_order_post() {
    $this->is_logged_in();

    $this->load->model('Order_model');
    $this->load->model('Order_item_model');

    $this->db->trans_start(); // Begin transaction

    try {
        $orderId = $this->Order_model->create([
            'user_id'     => $this->jwt_data->user_id,
            'total'       => $this->post('total'),
            'status'      => 'pending',
        ]);

        if (!$orderId) {
            throw new \RuntimeException('Failed to create order');
        }

        $items = $this->post('items') ?: [];
        foreach ($items as $item) {
            $itemCreated = $this->Order_item_model->create([
                'order_id'   => $orderId,
                'product_id' => $item['product_id'],
                'quantity'   => $item['quantity'],
                'price'      => $item['price'],
            ]);

            if (!$itemCreated) {
                throw new \RuntimeException('Failed to create order item');
            }
        }

        $this->db->trans_complete(); // Commit

        $this->response([
            'status'  => true,
            'message' => 'Order created successfully',
            'data'    => ['order_id' => $orderId],
        ], REST_Controller::HTTP_CREATED);

    } catch (\Exception $e) {
        $this->db->trans_rollback(); // Rollback on failure

        log_message('error', 'Order creation failed: ' . $e->getMessage());

        $this->response([
            'status'  => false,
            'message' => 'Failed to create order. Please try again.',
        ], REST_Controller::HTTP_INTERNAL_SERVER_ERROR);
    }
}

Global Exception Handling

In application/config/config.php, enable hook-based error handling:

$config['log_threshold'] = 1; // Log error messages only

Create application/hooks/App_hook.php:

<?php
defined('BASEPATH') OR exit('No direct script access allowed');

class App_hook {

    /**
     * Catch 404 errors and return JSON for API routes.
     */
    public function handle_404() {
        $ci =& get_instance();

        // Only intercept API routes
        if (strpos($_SERVER['REQUEST_URI'], '/api/') !== false) {
            $ci->load->library('REST_Controller');

            $ci->response([
                'status'  => false,
                'message' => 'Endpoint not found',
            ], REST_Controller::HTTP_NOT_FOUND);
            exit;
        }
    }
}

8. Security

8.1 XSS Prevention

8.2 CSRF Protection

For REST APIs, CSRF is typically disabled because APIs use token-based auth (JWT). However, if your API also serves web views:

// In application/config/config.php
$config['csrf_protection']   = TRUE;
$config['csrf_token_name']   = 'csrf_token';
$config['csrf_cookie_name']  = 'csrf_cookie';
$config['csrf_expire']       = 7200;

// Exempt API routes from CSRF (in application/config/config.php or custom hook)
$config['csrf_exclude_uris'] = [
    'api/.*',   // Regex to exempt all API routes
];

8.3 SQL Injection Prevention

CI3's Query Builder automatically escapes values. Never bypass it.

// ✅ SAFE — Query Builder escapes automatically
$this->db->where('email', $email);
$this->db->get('users');

// ✅ SAFE — Parameterized with bind markers
$this->db->query('SELECT * FROM users WHERE email = ?', [$email]);

// ❌ DANGEROUS — Raw string interpolation
$this->db->query("SELECT * FROM users WHERE email = '$email'");

// ❌ DANGEROUS — Unescaped like/where with user input concatenated
$this->db->where("name LIKE '%" . $search . "%'"); // Use $this->db->like() instead

Anti-pattern checklist:

8.4 Additional Security Measures

Password hashing:

// Registration
$data['password'] = password_hash($this->post('password'), PASSWORD_BCRYPT, ['cost' => 12]);

// Verification
if (password_verify($this->post('password'), $user->password)) { /* valid */ }

Rate limiting (RestServer built-in):

// In application/config/rest.php
$config['rest_limits'] = [
    'api/products/index' => 60,   // 60 requests per hour
    'api/products/create' => 30,
    'api/auth/login'     => 10,   // Limit login attempts
];

Input sanitization before database:

// Filter only allowed fields (prevents mass assignment)
$allowed = ['name', 'email', 'role'];
$data    = array_intersect_key($input, array_flip($allowed));

// Strip null bytes
$data = array_map(function ($value) {
    return is_string($value) ? str_replace("\0", '', $value) : $value;
}, $data);

CORS headers (for client-side apps):

// In application/config/hooks.php
$hook['post_controller_constructor'] = [
    'class'    => 'Cors_hook',
    'function' => 'set_headers',
    'filename' => 'Cors_hook.php',
    'filepath' => 'hooks',
];

// application/hooks/Cors_hook.php
class Cors_hook {
    public function set_headers() {
        header('Access-Control-Allow-Origin: *');
        header('Access-Control-Allow-Methods: GET, POST, PUT, DELETE, PATCH, OPTIONS');
        header('Access-Control-Allow-Headers: Content-Type, Authorization, X-Requested-With');
        header('Access-Control-Max-Age: 86400');

        if ($_SERVER['REQUEST_METHOD'] === 'OPTIONS') {
            http_response_code(200);
            exit;
        }
    }
}

Environment-based secret management:

// .env (not committed)
JWT_SECRET=your-production-secret-here
DB_PASSWORD=secure-db-pass

// application/config/jwt.php
$config['jwt_key'] = getenv('JWT_SECRET') ?: 'fallback-dev-only';

9. Response Envelope (Standard Contract)

Every API response must follow this contract:

{
  "status":  "<boolean> true | false",
  "message": "<string> human-readable summary",
  "data":    "<object|array|null> payload (omitted on simple errors)"
}

For validation errors, include an errors object:

{
  "status":  false,
  "message": "Validation failed",
  "errors": {
    "field_name": "Error message for that field"
  }
}

For paginated lists, data contains:

{
  "status":  true,
  "message": "Products retrieved successfully",
  "data": {
    "items":    [ ... ],
    "total":    42,
    "page":     1,
    "per_page": 20,
    "pages":    3
  }
}

10. Verification & Testing

Curl Commands for Manual Testing

# Login
curl -X POST http://localhost:8000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"user@example.com","password":"secret123"}'

# List products (with JWT)
curl http://localhost:8000/api/products?page=1&limit=20 \
  -H "Authorization: Bearer <TOKEN>"

# Get single product
curl http://localhost:8000/api/products/1 \
  -H "Authorization: Bearer <TOKEN>"

# Create product
curl -X POST http://localhost:8000/api/products \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  -d '{"name":"New Product","price":29.99,"category_id":1}'

# Update product
curl -X PUT http://localhost:8000/api/products/1 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  -d '{"name":"Updated Name","price":39.99}'

# Delete product
curl -X DELETE http://localhost:8000/api/products/1 \
  -H "Authorization: Bearer <TOKEN>"

# Refresh token
curl -X POST http://localhost:8000/api/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{"refresh_token":"<REFRESH_TOKEN>"}'

Postman Collection

If the IT Leader's delegation includes postmanSync: true, use the api-documentation skill to sync a collection with:

1. Auth endpoints (login, refresh)
2. CRUD endpoints (list, detail, create, update, delete)
3. Error scenarios (401, 404, 422, 500)
4. Environment variables (base_url, token, refresh_token)

11. Quick Reference — File Creation Checklist

When building a new CRUD resource:

12. Do's and Don'ts

Do:

• Always use Query Builder for database interactions
• Always validate input with form_validation
• Always hash passwords with password_hash(PASSWORD_BCRYPT)
• Always return consistent response envelopes
• Always handle missing resources with 404
• Always log errors server-side with log_message()
• Always filter allowed fields before insert/update
• Use transactions for multi-table writes

Don't:

• Never use raw SQL with string interpolation
• Never expose stack traces or debug output in responses
• Never bypass JWT validation on protected endpoints
• Never store plaintext passwords
• Never trust user input without validation
• Never hardcode secrets in config files (use environment variables)
• Never allow mass-assignment without field whitelisting
• Never use extract() or parse_str() on user input
• Never commit .env files to version control

13. Common Mistakes

14. Skill Usage Examples

@ci3-rest-api Create GET /api/categories endpoint with JWT auth and pagination
@ci3-rest-api Add form validation for product create/update
@ci3-rest-api Implement JWT login/register flow
@ci3-rest-api Build soft-delete pattern for the inventory model
@ci3-rest-api Set up CORS and rate limiting for public endpoints

This skill provides complete CI3 REST API development patterns: RestServer controllers, JWT auth, CRUD models, form validation, security hardening, and consistent response contracts. Every endpoint follows the same predictable structure for maintainability and developer experience.