¿Cómo crear una API REST con CodeIgniter 3?

NUEVO POST para crear una Api Rest empleando CodeIgniter 4 

CodeIgniter es un framework muy versátil empleado generalmente para proyectos de pequeña o mediana envergadura; CodeIgniter tiene algunas carencias al no contar con funcionalidades casi fundamentales como un sistema de login como tampoco contar con alguna integración de manera nativa con alguna plataformas de pago, listas ACL, creación de APIs REST etc; sin embargo todas estas características pueden ser fácilmente implementadas empleando librerías de terceros que por lo general, tenemos algunas para escoger a las cuales se les da mantenimiento como la que le traemos en esta entrada.

¿Qué es una API REST?

Una API REST no es más que una librería de funciones o un conjunto de funciones creadas en una aplicación por las cuales se accede mediante HTTP desde la misma aplicación u otras sin importar la plataforma, es decir, podemos tener nuestros proyectos en PHP como módulo administrativo y crear unas aplicaciones para Android y accedemos a estos recursos que en otras palabras significa acceder mediante URLs para obtener distintos recursos mediante consultas o proveer información.

Las REST APIs ofrecen una manera sencilla de conectar diversas aplicaciones en distintas plataformas como se ha mencionado antes.

Los datos devueltos pueden ser en XML, JSON, HTML entre otros formatos aunque esto depende de lo que configuremos nosotros lo que lo hace de los más versatil para que distintas aplicaciones se conecten a la misma y de esta forma crear aplicaciones más complejas o con un mayor número de módulo con distintas tecnologías de una manera sencilla.

Las Rest APIs podemos crearlas nosotros desde cero, aunque muchas plataformas como es el caso de CodeIgniter nos facilitan el proceso y podemos instalar una librería fácilmente.

Integrando la API REST en CodeIgniter y creando nuestra RESTFUL

Como indicamos en un comienzo, emplearemos una librería PHP de un tercero para realizar esta labor; específicamente emplearemos la librería provista desde GitHub llamada: CodeIgniter Rest Server la cual es sencilla de implementar, emplear y hace su proposito; cuenta con algunas características extras como el manejo de API Keys y autenticación que en esta entrada no abordaremos pero puedes consultarlo en el enlace anterior.

Instalando la librería para la API REST de manera manual

Tal como indica la documentación oficial, para instalar la librería PHP anterior simplemente debemos copiar los siguientes archivos en nuestro proyecto CodeIgniter alojado en nuestro servidor Apache:

• Copiar los archivos application/libraries/Format.php y application/libraries/REST_Controller.php dentro de la carpeta library de nuestro proyecto.
• Copiar el archivo application/config/rest.php dentro de nuestra carpeta conf.

Con poco más de esto podemos, tenemos integrada esta librería PHP en nuestro proyecto CodeIgniter y empezar a crear nuestra API REST.

Recuerda colocar el

use Restserver\Libraries\REST_Controller; require APPPATH . '/libraries/REST_Controller.php'; require APPPATH . '/libraries/Format.php';

Una vez hecho esto, creamos un controlador en CodeIgniter y en vez de extender de MY_Controller hacemos que extienda de REST_Controller quedando de la siguiente manera:

defined('BASEPATH') OR exit('No direct script access allowed');
use Restserver\Libraries\REST_Controller;

class Restserver extends REST_Controller {

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

También podemos agregar la clase REST_Controller en el autoload del proyecto en vez del require.

Instalando la librería con composer

Desde la versión de CodeIgniter 3, el framework emplea composer de manera nativa y esta es otra forma que tenemos para instalar dicha librería en nuestro proyecto la cual es la recomendada.

Composer es un manejador de dependencias que permite instalar distintos paquetes y/o librerías en una carpeta llamada vendor:

La instalación es prácticamente automática aunque nos genera una gran cantidad de archivos como verás en la carpeta vendor.

Y es muy fácil de emplear, para emplear composer, en Linux lo puedes instalar desde la terminal como un programa más, en Windows que puede ser "más complicado" también es muy sencillo y podemos obtener composer al instalar GIT desde el siguiente enlace, luego abrimos el GIT Bash:

Y a posterior nos ubicamos sobre nuestro proyecto y ejecutamos el siguiente comando:

composer require chriskacerguis/codeigniter-restserver

Y veremos una dentro de nuestro composer.json que se ubica en la raíz de nuestro proyecto una nueva línea como la siguiente:

"chriskacerguis/codeigniter-restserver": "^3.0"

Con esto podemos hacer un composer update en la consola para que composer se encargue de resolver todas las dependencias de nuestro proyecto entre las que está la de CodeIgniter Rest Server en nuestro proyecto en caso de que aún no fuera resuelto en el paso anterior:

Manejando las peticiones de la API REST

Ya instalada la librería ya sea por composer o de manera manual, si la instalas de manera manual probablemente no te funcionen algunas características como la de pasar la data devuelta a los distintos modos que ofrece pero lo principal que es realizar las consultas y devolver la data por JSON funciona perfectamente.

Una vez tengamos nuestro ambiente configurado, pasamos a crear los métodos que conforman nuestra API REST.

En este pequeño ejemplo presentado, emplearemos un modelo supuesto de usuarios (users) el cual nos servirá para dar los primeros pasos con la API REST en CodeIgniter.

API REST para obtener todos los usuarios

Con el siguiente método podemos obtener todos los usuarios:

// se accede con http://miservidor/restserver/users?format=json
public function users_get() {
    $this->load->model('Users');
    $this->response($this->Users>findAll());
}

Para acceder al método anterior y que este nos devuelve un JSON empleamos la siguiente URL:

http://miservidor/restserver/users?format=json

Obtenemos:

[{"user_id":"274176531","username":"acy293","email":"desarrollolibre2.net@gmail.com","auth_level":"1" ...}]

Si en vez de un JSON deseamos un XML empleamos la siguiente URL:

http://miservidor/restserver/users?format=xml

Obtenemos:

<xml>
    <item>
        <user_id>274176531</user_id>
        <username>acy293</username>
        <email>desarrollolibre2.net@gmail.com</email>
        <auth_level>1</auth_level>
        <banned>0</banned>
        <passwd>
            $2y$11$f4ViF8bla.UWenXVywvDN.0DTLWPLexvn35zuLP1V.XlConvFKyLi
        </passwd>
        <passwd_recovery_code/>
        <passwd_recovery_date/>
        <passwd_modified_at>2016-06-12 12:46:09</passwd_modified_at>
        <last_login>2016-06-16 22:39:12</last_login>
        <created_at>2016-06-10 01:35:03</created_at>
        <modified_at>2016-06-16 16:39:12</modified_at>
    </item>
</xml>

Bastante sencillo; el nombre de nuestro método REST o recurso tiene dos partes:

• El nombre de nuestro método: users.
• Y la petición empleada para obtener el recurso mediante los métodos HTTP clásicos.

Aunque esto es por convención que en otras palabras podemos nombrarlo como queramos ya que somos nosotros los que decidimos que hace el método REST o recurso pero la cosa es que tenga cierta lógica; existen otros métodos provistos por el protocolo HTTP los cuales están estructurado de la siguiente manera:

• get: Para obtener datos.
• post: Para actualizar un recurso.
• delete: Para borrar un recurso.
• put: Para crear un recurso.

Siguiendo nuestro ejemplo nuestros recursos quedarían de la siguiente forma:

   function users_get()
    {
        // Para obtener datos
    }
 
    function users_put()
    {
        // Para crear un recurso
    }
 
    function users_post()
    {
        // Para actualizar un recurso
    }
 
    function users_delete()
    {
        // Para borrar un recurso
    }

Esta sería la forma más común de crear nuestra REST API no es obligatorio emplear esta estructura; es más, generalmente nunca se emplean los métodos put y delete ya que son pocos soportados por los navegadores.

Pase de parámetros a los recursos de la API REST

También puedes agregar parámetros a la URL, por ejemplo si queremos obtener el detalle de un elemento específico o borrar uno con delete:

public function index_delete($id) {
    $this->response([
        'returned from delete:' => $id,
    ]);
}  	

Puedes aplicar la misma lógica para los demás métodos HTTP mencionados anteriormente.

Autenticación y API Keys

CodeIgniter Rest Server cuenta con otras funcionalidades que podemos emplear, como el uso de API Keys y autenticación básica, segura mediante digest y empleando librerías propias, cuyos pasos puedes ver en la guía oficial.

Sin embargo a mi en lo particular me a dado algunos problemas la autenticación básica según los pasos en la guía y los diversos materiales en Internet no ayudaron mucho; también puedes implementar tu propio sistema de autenticación como el siguiente:

class Restserver extends REST_Controller {

    public function __construct() {
        parent::__construct();
        // cargo los modelos comunes
        $this->load->database();
        $this->load->helper('url');
        $this->load->library('session');
        $this->load->model('Users');

        if ($_SERVER['PHP_AUTH_USER'] == "root" && $_SERVER['PHP_AUTH_PW'] == "12345") {
            return true;
        }

        $this->error();
        exit;
    }

    private function error() {
        echo json_encode(["status" => "Bad authentication"]);
    }

   //demas funciones

}

Quedando nuestro código la siguiente forma:

Por supuesto, puedes colocar estas credenciales en la base de datos, en el index, etc, inclusive colocar esta "capa" de autenticación en otros archivos y/o clases para mantener más organizado el código.

Conclusiones

En general las APIs REST son muy útiles cuando queremos interconectar aplicaciones de distintas tecnologías como CodeIgniter con Android, IOS... en un supuesto caso de tener una aplicación administradora centralizada con CodeIgniter y la aplicación Android realiza consultas mediante la API REST, este sería uno de los escenarios más comunes debido al gran alcance que tienen las aplicaciones móviles hoy en días.