Desarrollo de una API REST para Redis usando Phalcon

Phalcon es un framework PHP open source que ofrece un alto rendimiento y un bajo consumo de recursos. Estas prestaciones se deben a que, a diferencia de otros frameworks, Phalcon se instala como una extensión C de PHP. Al ser una extensión de C:

• El framework se carga cuando arranca el proceso daemon del servidor web.
• Las clases y funciones proporcionadas por la extensión están disponibles para cualquier aplicación.
• El código del framework no tiene que ser interpretado ya que está compilado para la plataforma y procesador en el que corre.

Puedes descargar Phalcon en la zona de descargas de su web oficial. Allí están disponibles las descargas y las instrucciones de instalación para plataformas Linux, Mac, Windows, así como boxes Vagrant con entornos preconfigurados.

En este breve tutorial de configuración de Phalcon puedes encontrar los pasos para configurar Phalcon en una plataforma LAMP.

Proyecto básico API REST con Phalcon

Antes de ver cómo crear una API REST para Redis usando Phalcon, veamos primero cómo montar un ejemplo sencillo sin complicarnos con la base de datos. Concretamente se trata de crear una API REST con dos métodos GET. El primer método GET es un método básico, sin parámetros, que simplemente nos dice la hora actual. El segundo método GET saluda a la persona que se pase como parámetro.

Crearemos un proyecto denominado HelloPhalcon. Para nuestro ejemplo mínimo necesitaremos dos archivos:

• Un archivo .htaccess que contiene todas las reglas para reescribir las URLs que lleguen a nuestra aplicación.
• Un archivo index.php en el que iniciaremos Phalcon, definiremos las rutas permitidas y definiremos los handlers (funciones asociadas) para cada una de las rutas permitidas.

Entonces, la estructura básica de nuestro proyecto sería:

HelloRESTAPIPhalcon /
	.htaccess
	index.php

Puedes descargar este proyecto básico de API REST con Phalcon desde un repositorio en GitLab.

El archivo .htaccess

El archivo .htaccess se usa para reescribir todas las peticiones que lleguen a nuestra aplicación. En concreto, todas las URL’s se reescribirán hacia al archivo index.php, que será el que se encargue de implementar cómo dar respuesta a las peticiones permitidas por nuestra API.

Siempre utilizaremos el mismo archivo .htaccess. Por tanto, lo podremos copiar de proyectos anteriores.

El archivo index.php

Con Phalcon podemos crear aplicaciones “Micro-Framework”. Esto nos permite crear una aplicación PHP con muy poco código. Las aplicaciones Micro son adecuadas para implementar prototipos de una forma sencilla y APIs, éstas últimas el objetivo de este tutorial.

Para crear el archivo index.php de una API REST con Phalcon básicamente deberemos seguir cuatro pasos:

• Instanciar la clase \Phalcon\Mvc\Micro(), responsable de implementar la aplicación Micro.
• Añadir las rutas permitidas por nuestra aplicación, junto con su handler asociado. Las rutas son gestionadas internamente por Phalcon. Las rutas siempre deben comenzar por /. También incluiremos un método HTTP para indicar que sólo se atienda la petición para la ruta y el método HTTP indicados.
• Implementar los handlers de las rutas. Se trata de funciones que se ejecutarán cuando coincida la ruta.
• Atender la petición con el método handle() de la clase \Phalcon\Mvc\Micro()

Primeras líneas del archivo index.php

A continuación se muestra un archivo index.php que tomaremos como punto de partida. En él:

• Se instancia la clase \Phalcon\Mvc\Micro(), responsable de implementar una aplicación Micro.
• Se llama al método handle(), encargado de atender la petición que se ajuste a una de las rutas permitidas.

Definiendo las rutas y sus handlers en el archivo index.php

Nuestra API REST sólo atenderá las rutas que indiquemos.

En nuestro caso sólo atenderemos dos rutas: say/date, que nos dice la fecha actual; y /say/hello{name}, que saluda a la persona que se pase como parámetro.

A la ruta say/date le asociaremos una función denominada currentDate(). A la ruta say/hello{name} le asociaremos una función denominada greeting($name). Ambas funciones se podrán implementar de forma anónima al declarar la ruta, o bien implementarlas aparte. En este tutorial las implementaremos aparte, ya que produce un código más legible.

La función currentDate() para este ejemplo sencillo se limita a mostrar la fecha actual

Ahora veremos cómo pasar parámetros en una llamada a nuestra API. En nuestro ejemplo pasaremos un nombre a la ruta say/hello{name} para que la función greeting($name) salude a la persona con el nombre pasado como parámetro.

Sin embargo, suele ser habitual que el resultado de una petición GET en una API REST sea una cadena JSON. En PHP la podemos construir creando un array para mostrarlo con la función echo json_encode()

Añadiendo un handler para rutas no encontradas

Un detalle que no debemos olvidar es qué debe mostrar nuestra aplicación cuando se solicita una ruta no válida. De forma predeterminada, dado que el control de las rutas lo ha tomado nuestro index.php, si no se encuentra una ruta, no se mostraría nada.

Si queremos informar de un error, nuestra aplicación tendrá que implementar un handler Not Found en el index.php.

Por fin, nuestro archivo index.php preparado

Definición de la API

Una vez que hemos visto la técnica para crear una API REST básica PHP usando Phalcon, es importante comenzar el desarrollo de una API REST definiendo la API. En dicha definición se describirán los métodos HTTP permitidos. Para el ejemplo desarrollado tendríamos

Descarga el código de este proyecto

Puedes descargar el código del ejemplo básico de API REST con Phalcon del repositorio de GitHub.

Proyecto básico API REST para Redis con Phalcon

Aquí veremos cómo implementar una API REST para Redis con los métodos básicos: GET, POST, PUT y DELETE.

Definición de la API

Para ilustrar la creación de una API REST para Redis usando Phalcon nos limitaremos a mostrar los cuatro ejemplos básicos:

• GET: Recuperar un valor a partir de una clave
• POST: Crear un nuevo par clave-valor
• PUT: Modificar el valor de una clave
• DELETE: Eliminar una clave

Ejemplo de uso

Estructura del proyecto

La estructura básica de nuestro proyecto sería:

HelloRedisRESTAPIPhalcon /
	.htaccess
	index.php

El archivo .htaccess

El archivo .htaccess se usa para reescribir todas las peticiones que lleguen a nuestra aplicación. Comentamos anteriormente que siempre utilizaremos el mismo archivo .htaccess. Por tanto, lo podremos copiar de proyectos anteriores.

Definiendo las rutas y sus handlers en el archivo index.php

Nuestra API REST sólo atenderá las rutas siguientes:

En el código anterior también se indican los handlers que se encargarán de atender cada petición.

El handler home se encarga de mostrar el uso de la API.

El handler notFound redirigirá la ejecución al handler home, y mostrará el uso de la API en caso de acceder a una URL no válida.

Cuestiones de interés en el archivo index.php

• Cada función de la API que interactúe con la base de datos comenzará estableciendo una conexión con la base de datos y finalizará cerrando la conexión establecida.
• Las funciones que generan JSON, por ejemplo un GET, devuelven un array asociativo array(clave => valor).
• Los parámetros de la petición HTTP son recogidos con el método $app->request->getRawBody() proporciondo por Phalcon. Dicho método contiene los datos leídos en forma de array asociativo.

El archivo index.php

Descarga el código de este proyecto

Puedes descargar el código del ejemplo básico de API REST para Redis con Phalcon del repositorio de GitHub.