Continuando con el objetivo de aprender cosas nuevas, me decidí de que tengo que aprender un poco sobre Frameworks de PHP; solamente usé 2 en mi vida, CodeIgniter y Zend Framework y la verdad que no hice más que algo muy simple para testearlo, hace poco me enteré que Laravel era uno de los mejores actualmente, busqué tutoriales sobre como hacer una API RESTful en PHP o NodeJS, pero decidí tirarme más por PHP que estoy un poco más acostumbrado y encontré un tutorial para hacerlo pero con este framework que había escuchado nombrar, Laravel, y lo seguí.
Logré exitosamente seguir el tutorial y tener lo que necesitaba funcionando, el tutorial estaba en inglés y pedí permiso para traducirlo, ayer me confirmaron que me daban permiso así que lo publico a continuación en este post.
Antes que nada paso a explicar que es REST, el término es un acrónimo de REpresentational State Transfer, o Transferencia de Estado Representacional en español. Una API REST es una API, o librería de funciones, a la cual accedemos mediante protocolo HTTP, osea desde direcciones webs o URL mediante las cuales el servidor procesa una consulta a una base de datos y devuelve los datos del resultado en formato XML, JSON, texto plano, etc. Mediante REST utilizas los llamados Verbos HTTP, que son GET, POST, PUT y DELETE.
¿En qué me sirve usar una REST API ?
Algo que aprendí ultimamente, es que es bastante útil para sitios dinámicos tener una API que devuelva JSON, por el simple hecho de que esa información después la podemos procesar mediante Javascript y dejar solamente al backend el trabajo de hacer la consulta y devolver el JSON, pero también el mismo resultado lo podemos utilizar mediante PHP. El fín de la API REST es tener más ordenado nuestro código y además que pueda ser accesible mediante la URL, no tener que andar haciendo consultas a una base de datos en cada fichero, si no solamente llamar a nuestra API y que nos devuelva el JSON.
En el caso que voy a detallar a continuación, la API será creada para hacer un To-Do List, osea, una lista de tareas, entonces mediante la API vamos a poder hacer lo siguiente:
- GET /tareas – mostrar todas las tareas
- GET /tareas/id – mostrar tarea con ID equivalente al ID de la URL
- POST /tareas – crear una nueva tarea
- PUT /tareas/ – actualizar una tarea con el ID enviado a la aplicación
- DELETE /tareas/id – eliminar una tarea con ID equivalente al ID de la URL
bien, eso sería lo que haríamos con nuestra API, ahora a trabajar.
Instalación de Laravel
En el sitio web de Laravel podemos descargar la versión estable, aunque también podemos simplemente darle git clone a su repositorio en github.
Tras descargarlo, y subirlo a nuestro servidor debemos asegurarnos que el directorio storage/views tenga permitida la escritura y además configurar la aplicación desde config/application.php especialmente la opción application key.
En mi caso recomiendo, si utilizamos un hosting con cPanel hacer lo siguiente, crear un subdominio, en mi caso, api.misitio.com desde el panel, y en el directorio del subdominio ingresar /api/public/
Si hacemos esto, recuerden subir el directorio al directorio raiz de nuestra cuenta de hosting, no al directorio public_html o www.
¿Porqué hacemos esto último? Porque los archivos que tienen que ser visibles mediante la URL solamente deben ser los que están en la carpeta Public, los demás no.
Tras haber realizado esto, ya tenés Laravel instalado, comprobalo yendo a api.tusitio.com o a la URL donde esté la carpeta public de la instalación de Laravel. Si no funciona, intentalo de nuevo, o fijate en la documentación de Laravel, seguramente algo estáss haciendo mal.
Creación y configuración de la Base de Datos
En algun lado tenemos que poner los elementos de nuestra lista de tareas, en este caso vamos a utilizar una base de datos MySQL, la vamos a llamar api, y debemos configurar la conexión a la base mediante el archivo que está en /application/config/database.php, en la linea 70 deberíamos editarlo de tal forma que quede algo así pero con nuestros datos, obviamente:
'mysql' => array( 'driver' => 'mysql', 'host' => '127.0.0.1', 'database' => 'nombre de la BD', 'username' => 'usuario de la BD', 'password' => 'contraseña', 'charset' => 'utf8', 'prefix' => '', ),
Ahora nos queda crear la tabla de la base, esto lo podemos hacer manualmente desde phpMyAdmin, pero vamos a hacerlo más rápido ingresando el SQL directamente, solo tenemos que pensar un par de cosas.
Cada tarea va a necesitar lo siguiente, un ID, un título (el nombre de la tarea), completada (si o no) y los timestamps de cuando fue creado y editado. Exactamente el SQL sería así:
CREATE TABLE `tareas` ( `id` int(10) unsigned NOT NULL AUTO_INCREMENT, `titulo` varchar(255) NOT NULL, `completada` varchar(4) NOT NULL, `created_at` datetime NOT NULL, `updated_at` datetime NOT NULL, PRIMARY KEY (`id`) ) ENGINE=InnoDB DEFAULT CHARSET=latin1 AUTO_INCREMENT=1 ;
Con esto ya tendría que estar todo OK.
Bueno, para comenzar con la parte de PHP en Laravel, vamos a editar el archivo /application/routes.php, ahí debemos agregar esto:
Route::any('v1/tareas/(:num?)', array('as' => 'api.tareas', 'uses' => 'api.tareas@index'));
Ahora nos queda crear nuestro modelo, este deberá ser el fichero /application/models/tarea.php que debemos crear con el siguiente contenido:
<?php
class Tarea extends Eloquent {
}
?>
Y ya tenemos nuestro modelo, pero ¿que hicimos con esto? Exactamente fue extender nuestro modelo con los métodos Eloquent de Laravel, que son increibles para trabajar con información, y nosotros podemos utilizarlos para utilizar su potencial para nuestra aplicación, específicamente para devolver un modelo Eloquent como una respuesta JSON, esto es posible ingresando algo como esto en tu controlador:
return Response::eloquent(Tarea::find(1));
Con eso nos devolvería en JSON la tarea con ID 1, es genial, nos simplifica el laburo.
Tras agregado esto deberíamos trabajar nuestro controlador, así que vamos a agregar el controlador que utilizaremos para el sitio, antes que nada tenemos que tener claro lo que va a ser el controlador.
El controlador se encargará de procesar 4 acciones diferentes, que habiamos comentado antes igual.
- GET index (ID) debe regresar todas las tareas codificadas en el formato JSON si es que no se especifica un ID; si se especifica se mostrará el objeto de la tarea que tenga ese ID
- POST index debe tomar el JSON que enviamos y crear una nueva tarea y guardarla en la base de datos. Nosotros podemos regresar el objeto JSON-ificado a la aplicación para dejar en claro que se creó.
- PUT index debe recibir una entrada que contiene la información ID, título y completada, entonces debe chequear si la Tarea con ese ID existe y actualizarla con la información nueva
- DELETE index (ID) debe recibir un ID como parámetro, entonces, busca la tarea con ese ID y lo elimina de la base de datos, si no existe la tarea devuelve un error.
Bien, ya tenemos en claro que queremos hacer, entonces crearemos el archivo /application/controllers/api/tareas.php con el siguiente contenido:
<?php
class Api_Tareas_Controller extends Base_Controller {
public $restful = true;
public function get_index($id = null)
{
if (is_null($id ))
{
return Response::eloquent(Tarea::all());
}
else
{
$tarea = Tarea::find($id);
if(is_null($tarea)){
return Response::json('Tarea no encontrada', 404);
} else {
return Response::eloquent($tarea)
}
}
}
public function post_index()
{
$nuevatarea = Input::json();
$tarea = new Tarea();
$tarea->titulo = $nuevatarea->titulo;
$tarea->completada = $nuevatarea->completada;
$tarea->save();
return Response::eloquent($tarea);
}
public function put_index()
{
$actualizartarea = Input::json();
$tarea = Tarea::find($actualizartarea->id);
if(is_null($tarea)){
return Response::json('Tarea no encontrada', 404);
}
$tarea->titulo = $actualizartarea->titulo;
$tarea->completada = $actualizartarea->completada;
$tarea->save();
return Response::eloquent($tarea);
}
public function delete_index($id = null)
{
$tarea = Tarea::find($id);
if(is_null($tarea))
{
return Response::json('Tarea no encontrada', 404);
}
$tareaeliminada = $tarea;
$tarea->delete();
return Response::eloquent($tareaeliminada);
}
}
?>
Con esto ya está todo listo con nuestra API, ahora nos falta probarla!
Vamos a ir a la dirección de nuestra API, que debería ser algo como api.misitio.com/v1/tareas/ y nos debe devolver un Array de Javascript vacío: []
Ahora viene una parte genial, para ello debemos probarlo utilizando una terminal Linux o Mac, o bueno también desde un sitio web, en el caso de Linux o MAC sería algo así, para obtener todas nuestras tareas debemos incresar lo siguiente:
curl -H “Accept: application/json” -H “Content-type: application/json” -X GET http://api.misitio.com/api/v1/tareas/
Esto nos devolvería el Array vacío: []
Ahora vamos a probar ingresar una nueva tarea, esto los hacemos con estas lineas de comando:
curl -H “Accept: application/json” -H “Content-type: application/json” -X POST -d ‘{“titulo”:”Mi primera tarea”,”completada”:”no”}’ http://api.misitio.com/api/v1/tareas/
esto debería devolver algo así:
{“titulo”:”Mi primera tarea”,”completada”:”si”,”updated_at”:{“date”:”2012-11-16 23:15:18″,”timezone_type”:3,”timezone”:”UTC”},”created_at”:{“date”:”2012-11-16 23:15:18″,”timezone_type”:3,”timezone”:”UTC”},”id”:1}
Para modificar sería así:
curl -H “Accept: application/json” -H “Content-type: application/json” -X PUT -d ‘{“id”:”1″,”titulo”:”Primera tarea modificada”,”completada”:”si”}’ http://api.misitio.com/api/v1/tareas/
y nos devolvería el JSON de la tarea editada.
Ahora, para borrar es así:
curl -H “Accept: application/json” -H “Content-type: application/json” -X DELETE http://api.misitio.com/api/v1/tareas/1
Y con eso eliminaríamos la tarea con ID 1
Bien, ¿todo funciona OK? Si esto es correcto, tu API está completada, podes seguir jugando con ella desde la linea de comandos, pero… ¿Qué tiene de divertido eso?
En la segunda parte del tutorial se explicará como haremos la parte visible de nuestra aplicación, la que tomará los datos de la API, procesará y mostrará en una linda Lista de Tareas.
Cuando tenga un poco más de tiempo publicaré la tercera parte traducida, mientras tanto pueden verla igual en este link.
También te puede interesar
Más lecturas cerca de este destino o tema.
Deja un comentario