CalaAPI Intro - CRLibre/CalaAPI GitHub Wiki

CalaAPI es un framework diseñado para crear APIS sobre el. CRLibre utiliza la misma para el desarrollo del API para Factura Electrónica con el Ministerio de Hacienda.

Esta es una herramienta bastante útil, ya que nos permite crear nuestro backend de manera segura y escalable. El API está diseñada para solamente cargar los módulos necesarios por cada carga, a diferencia de otro tipo de herramientas como esta, que cargan todos los módulos, aunque no sean necesarios en cada carga.

Esta API es de uso gratuito, de código abierto la cual está bajo licencia MIT y desarrollada en su gran mayoría por Felipe Escoto Murillo y por varios aportes realizados por Julián Subirós Murillo.

Hoy en día se encuentra en desarrollo por miembros de CRLibre, organización que nace con el fin de desarrollar código abierto y de uso gratuito, primeramente para cubrir necesidades en el ámbito nacional, tal como Factura Electrónica.

Agradecemos la participación de todos los que de una u otra manera han ayudado al desarrollo y programación de esta herramienta. De la comunidad para la comunidad.

### Instalación de API:

Antes de comenzar, es necesario contar con las diferentes dependencias necesarias.

PHP >= 5.3.0 MySQL / MariaDB Apache o cualquier CGI para PHP Librerías: php-xml, php-curl

Preferiblemente utilizar Linux.

Primeramente hay que comprender la estructura o funcionamiento del CalaAPI, ya que está funciona como una sólida base que nos permite extender y crear sobre ella por medio de módulos.

En este caso, el API cuenta con los módulos para realizar las diferentes tareas necesarias para la conexión con el Ministerio de Hacienda, así mismo como lo necesario para formatear la información y realizar las solicitudes necesarias. Lo único que es necesario, es tener la información de cada documento para realizar los diferentes procedimientos.

Es necesario identificar las 2 carpetas que estaremos utilizando. La primera es ‘www’, esta carpeta debe estar en una sección púbica de su servidor y es nuestra puerta de entrada a los diferentes módulos. Dentro de esta carpeta se encuentra un documento en php que se llama api.php. A este documento es al que se le deben hacer las diferentes solicitudes, ya sean POST, GET o por terminal.

Adicional se encuentra otro documento ‘settings.php’, en este se debe ingresar la configuración de la conexión a la base de datos y la ubicación de en donde se encuentra la segunda carpeta contigua a ‘www’, la cual tiene como nombre ‘api’.

¿Por qué está separado en 2 secciones?

La idea de esto es que el ‘www’ esté en una sección pública, y el resto del API con nuestros módulos, se encuentre en una sección en donde no sea abierto o accesible de manera pública. Esto nos brinda seguridad adicional en caso de que haya intromisión dentro del servidor y los documentos del API se encuentren resguardados por la seguridad del servidor o bien, de su sistema operativo. Por esta razón recomendamos utilizar un sistema Linux o basado en Unix. Una vez que agreguemos los valores correctos en el ‘settings.php’, y tengamos nuestras carpetas en los lugares que queremos, podemos proceder a probar el API.

Un ejemplo de cómo se podría ver bajo un sistema Linux, sería algo como.

Ubicación del ‘www’:

/var/www/html/miApi/www

Ubicación del ‘api’:

/home/user/subs/miApi/api

La dirección de la segunda carpeta debe ser indicada en el ‘settings.php’, como se indica arriba.

En caso de necesitar ayuda adicional, puede ponerse en contacto por medio de nuestra página en Facebook y con gusto le ayudaremos.

Seguidamente es necesario que la base de datos a la cual se referencia en ‘settings.php’ cuente con sus diferentes tablas. De tal manera, el importable se encuentra en api/install/cala_base.sql

Para probar si el API está funcionando, debemos hacer un request al ‘api.php’. Bajo el mismo ejemplo, entonces sería algo como http://localhost/miApi/www/api.php y el resultado debería ser algo como {“resp”:-1}. En caso de que esto salga, el API sí está funcionando y en caso de que no haya ningún error, entonces vamos por buen camino.

La razón por la cual se presenta este -1, es debido a que no estamos realizando ningún request. Para realizar un request, es necesario que el API sepa qué necesitamos que ella haga. Esto lo definimos según los parámetros que enviemos en cada uno de nuestros requests.

Existen diferentes módulos propios del API, tales como para gestionar usuarios, archivos o documentos, entre otros.

Estos se encuentran en la carpeta api/modules.

Los módulos adicionales, o bien, los que construimos sobre CalaAPI, los debemos crear en api/contrib. En esta carpeta se encuentra un ejemplo de un módulo base para basarse y crear los propios módulos.

El beneficio principal de este tipo de esquema u organización, es que nos permite utilizar selectivamente los recursos de nuestro servidor, ya que CalaAPI no carga todos nuestros módulos en cada request, sino que solamente carga los necesarios para el funcionamiento mismo, y cualquier módulo al cual nosotros necesitemos acceso según sea definido en el request.

Los 2 parámetros principales son ‘w’ y ‘r’, ya que con estos definimos a cual módulo necesitamos y qué es lo que necesitamos de él. Un ejemplo de esto, el cual nos sirve para probar la instalación, podemos utilizar ‘w = cala’ y ‘r = cala_test_install’. Dando como resultado para un request tipo GET:

http://localhost/miApi/www/api.php?w=cala&r=cala_test_install

En donde estaríamos utilizando un llamado al módulo ‘cala’ y lo que necesitamos del mismo es ‘cala_test_install’. Este llamado debe dar un resultado con información respecto a la instalación.

Nota: Nuestra carpeta ‘www’ puede tener cualquier nombre y puede estar ubicada en cualquier lugar e incluso en diferentes lugares simultaneamente. Lo que se necesita es que la información de ‘settings.php’ sea la correcta y que los contenidos de la carpeta se encuentren en sus lugares correctos. El ‘api.php’ debe estar en un lugar con acceso público en caso de que se desee hacer requests al API de manera remota.